Feedback and status

Scroll progress

<forma-scroll-progress>

Decorative reading-progress bar driven directly by the scroll timeline: no smoothing or lag, absent without scroll timelines or under reduced motion.

Authoring tag
<forma-scroll-progress>
Behavior owner
Native HTML
Canonical source
patterns/scroll-progress.html

Purpose

A scroll progress bar is a thin strip that fills as the reader moves through a long page. Forma drives it entirely with a CSS scroll timeline tied to the root scroller (scroll(root block)), so its fill is a direct function of the page's scroll position with no smoothing. It is decorative and aria-hidden: the scrollbar and headings remain the real indication of position, and nothing may be triggered by the bar reaching a point.

Use when

  • A long, linear document such as release notes, a policy or an article benefits from a light sense of how much remains.
  • The page scrolls as a whole (the document is the scroller).

Avoid when

  • The reader needs to know their position precisely or jump to a section: provide a table of contents or Entry index instead.
  • Progress through a task or form: use Progress bar, Steps or Survey progress.
  • The content scrolls inside a nested container; the bar tracks the root scroller only and would not reflect it.

Behavior to know

  • Hidden entirely where animation-timeline: scroll() is unsupported, because a static bar could not be truthful.
  • Hidden under prefers-reduced-motion: reduce.
  • pointer-events: none: it never blocks clicks or taps on content beneath it.

Basic example

The smallest correct markup: the canonical pattern from patterns/scroll-progress.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal scroll progress

Rendered from the canonical pattern file.

Release notes

The reading-progress bar above is a decorative projection of the page's scroll position. It adds no lag, triggers nothing, and is absent where scroll timelines are unsupported or reduced motion is requested.

The scrollbar and the headings remain the authoritative way to know where you are in the document.

HTML · Minimal scroll progress Raw HTML for HTML · Minimal scroll progress
<forma-scroll-progress class="forma-component-tag">
<div class="forma-scroll-progress" aria-hidden="true"></div>
<article class="forma-stack">
  <h2>Release notes</h2>
  <p>The reading-progress bar above is a decorative projection of the page's scroll position. It adds no lag, triggers nothing, and is absent where scroll timelines are unsupported or reduced motion is requested.</p>
  <p>The scrollbar and the headings remain the authoritative way to know where you are in the document.</p>
</article>
</forma-scroll-progress>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Documentation article

The bar placed as the first child of an article so it sticks to the top of the viewport while the article is on screen. In this catalog page it reflects the scroll position of the whole page, not of this example.

Data retention policy

This policy describes how long each class of record is kept and who may approve an exception.

Scope

It applies to every workspace, including archived workspaces that still hold customer data.

Retention periods

Financial records are kept for seven years. Support conversations are kept for two years after the case closes.

HTML · Documentation article Raw HTML for HTML · Documentation article
<forma-scroll-progress class="forma-component-tag">
  <article class="forma-stack" aria-labelledby="scroll-progress-documentation-article-title">
    <div class="forma-scroll-progress" aria-hidden="true"></div>
    <h2 id="scroll-progress-documentation-article-title">Data retention policy</h2>
    <p>This policy describes how long each class of record is kept and who may approve an exception.</p>
    <h3>Scope</h3>
    <p>It applies to every workspace, including archived workspaces that still hold customer data.</p>
    <h3>Retention periods</h3>
    <p>Financial records are kept for seven years. Support conversations are kept for two years after the case closes.</p>
  </article>
</forma-scroll-progress>

Click or tap the code once to select all of it, then copy.

Scenario

Right-to-left document

In a right-to-left context the bar fills from the right edge. The transform origin follows :dir(rtl), so no extra attribute is needed on the bar itself.

ملاحظات الإصدار

يعرض شريط التقدم موضع القراءة في الصفحة فقط ولا يغني عن العناوين.

HTML · Right-to-left document Raw HTML for HTML · Right-to-left document
<forma-scroll-progress class="forma-component-tag">
  <article class="forma-stack" dir="rtl" lang="ar" aria-labelledby="scroll-progress-right-to-left-title">
    <div class="forma-scroll-progress" aria-hidden="true"></div>
    <h2 id="scroll-progress-right-to-left-title">ملاحظات الإصدار</h2>
    <p>يعرض شريط التقدم موضع القراءة في الصفحة فقط ولا يغني عن العناوين.</p>
  </article>
</forma-scroll-progress>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile release notes

The bar at the top of a long article on a phone.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • The bar is 0.1875rem (3px) tall and spans the article's full width at every screen size.
  • It sticks to the top edge while the article is in view and scrolls away with the article after it ends.
  • It ignores pointer and touch input, so it never covers or intercepts taps on content under it.
  • Rotation changes the scrollable length; the fill recalculates directly from the new scroll position without lag.
HTML · Mobile release notes Raw HTML for HTML · Mobile release notes
<forma-scroll-progress class="forma-component-tag">
  <article class="forma-stack" aria-labelledby="scroll-progress-mobile-release-notes-title">
    <div class="forma-scroll-progress" aria-hidden="true"></div>
    <h2 id="scroll-progress-mobile-release-notes-title">Release 4.2</h2>
    <p>Bank feeds now import pending transactions separately from posted ones.</p>
    <p>Approval rules can require two approvers above a configurable amount.</p>
    <p>Exports include the approver of each payment and the time of approval.</p>
    <p>The mobile app shows the last verified time on every balance.</p>
  </article>
</forma-scroll-progress>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
aria-hiddendiv.forma-scroll-progresstrue—Required. The bar is decorative and must not be exposed to assistive technology.
diran ancestorrtl | ltrinheritedIn right-to-left contexts the bar fills from the right.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-scroll-progressBlock class—The bar: sticky at the top of its container, 3px tall, accent colored, scaled horizontally by the root scroll timeline. Not displayed without scroll-timeline support or under reduced motion.
Keyboard interaction
KeysResult
—Not focusable. Keyboard scrolling (Space, Page Down, arrow keys) moves the page and the bar follows.
Events
EventDescription
—None. Do not attach behavior to the bar's visual state.

Form behavior

Not a form control.

States

Scroll progress states
StateHow it is expressedPresentation
Tracking@supports (animation-timeline: scroll())Fill equals the root scroller's block progress, from empty at the top to full at the bottom.
Absentno scroll-timeline support, or prefers-reduced-motion: reducedisplay: none. The page reads and scrolls normally.

Accessibility

Forma provides

  • Hides the bar from assistive technology and from pointer input.
  • Removes it under reduced motion and where it cannot be accurate.
  • Never gates content or actions on the bar.

Your application supplies

  • Keep aria-hidden="true" on the bar.
  • Provide headings, and for long documents a table of contents, as the real navigation aids.
  • Use only one scroll progress bar per page.

Responsive behavior

  • Full width of its container at every size; height is fixed at 0.1875rem.
  • position: sticky with inset-block-start: 0 keeps it at the top only while its containing block is on screen.
  • It tracks the root (document) scroller, so it is meaningful only on pages that scroll as a whole.

Motion

  • The fill is a CSS animation on scale bound to animation-timeline: scroll(root block) with linear timing: a direct projection of scroll position, with no spring, easing or lag layered on top.
  • Scrolling backwards empties the bar at the same rate; there is no momentum of its own.
  • Under prefers-reduced-motion: reduce the bar is removed rather than shown static, because a frozen bar would be untrue.

Usage guidance

Do

  • Place it as the first child of the long content it describes.
  • Reserve it for long, linear reading.

Avoid

  • Using it inside nested scrolling panels.
  • Triggering analytics, completion or unlocks from the bar reaching the end.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.