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.
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.
<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.
<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.
ملاحظات الإصدار
يعرض شريط التقدم موضع القراءة في الصفحة فقط ولا يغني عن العناوين.
<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.
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.
<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.
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
Attribute
On
Values
Default
Description
aria-hidden
div.forma-scroll-progress
true
—
Required. The bar is decorative and must not be exposed to assistive technology.
dir
an ancestor
rtl | ltr
inherited
In right-to-left contexts the bar fills from the right.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-scroll-progress
Block 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
Keys
Result
—
Not focusable. Keyboard scrolling (Space, Page Down, arrow keys) moves the page and the bar follows.
Events
Event
Description
—
None. Do not attach behavior to the bar's visual state.
Form behavior
Not a form control.
States
Scroll progress states
State
How it is expressed
Presentation
Tracking
@supports (animation-timeline: scroll())
Fill equals the root scroller's block progress, from empty at the top to full at the bottom.
Absent
no scroll-timeline support, or prefers-reduced-motion: reduce
display: 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.
Release notes · Extended localized content for verification and layout resilience
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.
Text spacingengineering screen
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.
Cue dropout · grayscaleengineering screen
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.
Reduced effective contrastengineering screen
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.