Scroll area
A box that scrolls your content with the platform's own scrolling and shows, at each edge it watches, that more lies beyond it — a band in the surface's color, a fade of the content, a line or a blur — without changing its size or moving the content.
- Category
- Containment
- Tokens
comp.scroll-area- Level
- Base
- Web
tanrei-scroll-areaclock_loader_40 - SwiftUI
TanreiScrollArearadio_button_unchecked - Jetpack Compose
TanreiScrollArearadio_button_unchecked - Flutter
TanreiScrollArearadio_button_unchecked - React Native
ScrollArearadio_button_unchecked
Generated from docs/status/status.json, specs/scroll-area.spec.json
A list in a box of a fixed height
The area draws nothing of its own while its content fits. Scroll it: the bottom edge is marked while more lies below, and the top edge once something has scrolled out of view above.
The Web and React samples show the current spec. SwiftUI, Compose, Flutter and React Native are planned: they do not ship a scroll area yet.
<!-- The layout gives the area its size; it marks its top and bottom edges by default. -->
<tanrei-scroll-area label="Messages" style="block-size: 20rem">
…
</tanrei-scroll-area>
<!-- On a filled card: the shadow takes the card's color, so that the list sinks into the card. -->
<tanrei-scroll-area label="Results" style="--tanrei-comp-scroll-area-shadow-color: var(--tanrei-comp-card-filled-container-color); block-size: 16rem">
…
</tanrei-scroll-area>
<!-- Over a picture or a video: the content itself fades, and no color is drawn. -->
<tanrei-scroll-area scroll-edge="fade" label="Captions">…</tanrei-scroll-area>
<!-- A row that scrolls sideways: mark its start and end edges. -->
<tanrei-scroll-area edges="start end" label="Photos">…</tanrei-scroll-area>
<script type="module">
import '@tanrei/web/components/scroll-area';
</script>import { ScrollArea } from '@tanrei/react';
<ScrollArea label="Messages" style={{ blockSize: '20rem' }}>
{messages}
</ScrollArea>
{/* On a filled card: the shadow takes the card's color. */}
<ScrollArea
label="Results"
style={{ '--tanrei-comp-scroll-area-shadow-color': 'var(--tanrei-comp-card-filled-container-color)', blockSize: '16rem' } as React.CSSProperties}
>
{results}
</ScrollArea>
<ScrollArea scrollEdge="fade" label="Captions">{captions}</ScrollArea>
<ScrollArea edges={['start', 'end']} label="Photos">{photos}</ScrollArea>Scroll edges: shadow (the default system's choice), fade, line, blur and none
Shadow. A band in the color of the surface the area stands on, full at the edge and none 24 in from it. Scroll to see the top edge marked too. The content seems to sink into the surface.
Fade. The content itself fades out toward the edge, and no color is drawn, so whatever lies behind the area shows through. Scroll to see the top edge marked too.
Line. A hairline along the edge, in the color of a divider, while content lies beyond it. Scroll to see the top edge marked too, and the bottom line go.
Blur. The content is blurred in a band 48 deep, most at the edge and none at the band’s inner end. Scroll to see the top edge marked too.
None. Nothing marks the edges: only the platform’s scroll bar says that the content goes on. Scroll it to compare with the others.
Anatomy
| Part | Description |
|---|---|
1 container | The scroll box: as large as its layout gives it, scrolling the content up and down, sideways or both where it does not fit, with the platform's own scrolling and scroll bars. It has no fill, edge or corner of its own. |
2 content | Whatever the product puts in it: a list, a column of cards, a form, a row of pictures. The area lays nothing out and styles nothing inside it. |
3 scroll-edge · optional | The mark at one edge of the box while content lies beyond that edge: a band in the color of the surface the box stands on, full at the edge and none at its inner end; a fade of the content itself toward the edge; a line along it; or a band in which the content is blurred, most at the edge. Drawn over the content (the fade, on it), taking no input. |
4 focus-ring · optional | The system's focus indicator inside the box's edge, while the box itself has keyboard focus. |
Properties
| Property | Type | Default | Description |
|---|---|---|---|
scrollEdge | auto | shadow | fade | line | blur | none | "auto" | How an edge shows that content lies beyond it. shadow: a band in the color of the surface the area stands on, so that the content sinks into the surface. fade: the content itself fades out toward the edge and no color is drawn, for a transparent surface, a picture or a video behind the area. line: a hairline along the edge. blur: the content blurred in a band along the edge, most at the edge. none: nothing. auto takes comp.scroll-area.scroll-edge, the design system's answer, which follows sys.behavior.scroll-edge (shadow in the default system). |
edges | strings | top,bottom | Which edges show the scroll edge: any of top, bottom, start and end. start is the left in a left-to-right layout and the right in a right-to-left one. |
label | string | "" | The name of the scroll box, for the moments it is a focus stop of its own (SCA-10): what it holds ("Messages", "Results"). Never drawn. |
Slots
| Slot | Description |
|---|---|
default | The content the area scrolls. A fixture's string is drawn as plain text in it. |
States
Behavior
Requirements in EARS form. Every platform implementation is tested against these ids.
| ID | Requirement |
|---|---|
SCA-1 | THE scroll area SHALL be as large as its layout gives it, SHALL lay its content out at its own width, and WHERE the content does not fit SHALL scroll it with the platform's own scrolling — wheel, trackpad, touch, scroll bars, keyboard and assistive technology — in each direction it does not fit; it SHALL draw no fill, edge, corner or elevation of its own, and SHALL NOT replace the platform's scroll bars. |
SCA-2 | WHILE content lies beyond an edge that edges names — the content is scrolled away from that edge, so that some of it is out of view past it — THE scroll area SHALL draw the scroll edge of that edge in the form its scroll edge (SCA-7) names; WHILE nothing lies beyond it, or the edge is not named, THE scroll area SHALL draw none there. Each edge SHALL be drawn and faded by itself: content beyond the top and none beyond the bottom draws the top edge only. |
SCA-3 | WHILE the scroll edge is shadow THE scroll area SHALL draw over the content, along the whole length of the edge and inside the box, a band comp.scroll-area.shadow.extent deep in comp.scroll-area.shadow.color — the color of the surface the area stands on, not a color of its own — full at the edge and falling smoothly to none at the band's inner end, and SHALL draw no line. |
SCA-4 | WHILE the scroll edge is fade THE scroll area SHALL fade the content itself along the edge, none of it shown at the edge rising smoothly to all of it at comp.scroll-area.fade.extent in from it, SHALL draw no color and no line, so that whatever lies behind the area — a transparent surface, a picture, a video — shows through where the content fades. |
SCA-5 | WHILE the scroll edge is line THE scroll area SHALL draw it as a line comp.scroll-area.line.width thick in comp.scroll-area.line.color along the whole length of the edge, inside the box. |
SCA-6 | WHILE the scroll edge is blur THE scroll area SHALL blur the content lying in a band comp.scroll-area.blur.extent deep along the edge, by comp.scroll-area.blur.radius at the edge falling to none at the band's inner end, in comp.scroll-area.blur.layers layers of evenly stepped radius, each masked to its part of the band so that no step is seen, and SHALL draw no line and no tint: the scroll area has no fill of its own to tint with. |
SCA-7 | THE scroll area SHALL take its scroll edge from scrollEdge: WHILE scrollEdge is auto, as comp.scroll-area.scroll-edge names, which follows sys.behavior.scroll-edge unless a design system sets the scroll area apart; WHILE it is shadow, fade, line, blur or none, as that value names, whatever the tokens say. WHEN scrollEdge, or the token it follows, changes THE scroll area SHALL draw the other form at once, keeping the scroll position and focus. |
SCA-8 | WHEN content starts or stops lying beyond an edge THE scroll area SHALL fade that edge's scroll edge in or out over comp.scroll-area.motion.duration with comp.scroll-area.motion.easing, and at once where motion is reduced; it SHALL NOT change its size, move the content, or change anything else it draws because of the scroll edge. It SHALL learn whether content lies beyond an edge from what the platform already knows of the scroll — its notice that a mark at that end of the content has entered or left the box, or the scroll's own extents — and SHALL NOT measure the content's layout in a frame of a scroll. |
SCA-9 | WHERE the platform cannot blur what lies behind a band (a browser without backdrop filters, Android before version 12, a platform where the product gave no blur view) THE scroll area SHALL draw shadow (SCA-3), the system's first form, in place of a blur; WHERE the platform draws with a person's own forced colors THE scroll area SHALL draw the line of SCA-5 in the platform's text color in place of a shadow, a fade or a blur. |
SCA-10 | WHILE the content does not fit and nothing inside the box takes keyboard focus THE scroll area SHALL make the box itself one stop in the focus order, exposed as a region named by label, so that a keyboard can scroll it (WCAG 2.1.1); WHILE something inside takes focus, or the content fits, THE scroll area SHALL NOT be a focus stop and SHALL expose no role of its own. WHILE it is a focus stop and label is empty it SHALL still be focusable, and in debug builds report that the region has no accessible name. |
SCA-11 | WHILE the box has keyboard focus THE scroll area SHALL show it as sys.behavior.focus-style names (ring or glow), drawn wholly inside its edge so that nothing around the box covers it, over every scroll edge and never faded by one, without animation, and never for focus gained by pointer or touch; a platform that cannot draw a choice SHALL fall back to the first value and state that in its README. |
SCA-12 | THE scroll area SHALL draw every scroll edge over the content (the fade, on the content itself), hidden from assistive technology, and SHALL let every press, hover and scroll over it reach the content under it. |
SCA-13 | WHERE the layout direction is right-to-left THE scroll area SHALL take start as its right edge and end as its left edge, SHALL begin a sideways scroll at the right, and SHALL mirror no scroll edge otherwise: each form is drawn the same toward whichever edge it stands at. |
SCA-14 | THE scroll area SHALL take its layout direction from where it is used — the direction of the nearest ancestor that sets one, and the platform's own where none does — and SHALL have no direction setting of its own; WHEN that direction changes while the area is shown THE scroll area SHALL draw itself for the new direction at once, keeping its scroll position from the start edge. |
SCA-15 | IF scrollEdge names a value the component does not define THE scroll area SHALL treat it as auto, IF edges names a value other than top, bottom, start and end THE scroll area SHALL ignore it, and in debug builds report the unknown value. |
SCA-16 | WHILE the text size is enlarged THE scroll area SHALL keep its scroll edges at their sizes and lay out the larger content, which scrolls further: a scroll edge is a mark of the box, not of its text. |
SCA-17 | THE scroll area SHALL have no words of its own and SHALL read none of the product's words: label names this one region. |
SCA-18 | WHERE the platform has ARIA attributes (the web), WHEN the product sets an aria- attribute on the host, by the attribute or by the ARIA property that reflects it, THE scroll area SHALL move it to the data-aria- attribute of the same name, so that the host is no second node with its name, description or state, and SHALL expose it on its box — an id reference by the elements it names in the host's tree or a tree around it, a description after its own — but a name only while the box is a focus stop and a region (SCA-10): then label is its name over a name given so, and while label is empty a name given so is its name and SHALL NOT be reported as having none in debug builds. WHILE the box is not a focus stop it has no role a name could stand on: THE scroll area SHALL expose no name the product gives on the host, and SHALL report it in debug builds. WHEN the product removes the aria- attribute or its data-aria- twin, or sets the ARIA property that reflects it (ariaLabel, ariaDescribedByElements…) to null, THE scroll area SHALL take it off the box. |
Platform name mapping
Parity does not mean identical APIs. Each platform uses its own idiom for the same contract.
| Spec | Web | SwiftUI | Jetpack Compose | Flutter | React Native |
|---|---|---|---|---|---|
| Component | tanrei-scroll-area | TanreiScrollArea | TanreiScrollArea | TanreiScrollArea | ScrollArea |
scrollEdge · Property | scrollEdge | scrollEdge | scrollEdge | scrollEdge | scrollEdge |
edges · Property | edges | edges | edges | edges | edges |
label · Property | label | label | label | label | label |
| Notes | <tanrei-scroll-area scroll-edge edges="top bottom" label>; edges is a space-separated attribute and an array property. Whether content lies beyond an edge is read from one IntersectionObserver on four thin sentinels at the ends of the content (SCA-8): no scroll listener, no layout read while scrolling. Not CSS scroll-driven animations: they are not in every engine, and they tie the mark to the distance scrolled rather than fading it over the state motion. shadow is a gradient band per edge in --tanrei-comp-scroll-area-shadow-color; set that custom property on the element, or on an ancestor, to the surface it stands on. fade is a mask-image on the scroll box, one gradient per axis, moved by mask-position and mask-size (no registered custom property), so the browser's scroll bar fades with the content at a faded edge. blur is blur.layers layers inside each band, each with backdrop-filter: blur(r × i / n) and a mask-image gradient; @supports not (backdrop-filter: blur(1px)) draws shadow (SCA-9). Every mark is pointer-events: none and aria-hidden. A fixture fills the slot with enough lines (or a row wide enough) to scroll, in a box of a fixed size, scrolled to the middle. | A ScrollView. onScrollGeometryChange tells whether content lies beyond an edge. shadow is a LinearGradient overlay from the surface color; fade a mask of a gradient; on iOS 26 and macOS 26 blur is the system's scrollEdgeEffectStyle(.soft, for:) and line .hard with the line drawn by Tanrei, before them blur is a Material band under a gradient mask. | A verticalScroll/horizontalScroll box (or the product's lazy list through a ScrollState/LazyListState parameter); canScrollBackward/canScrollForward tell the edges. shadow is a drawWithContent gradient in the surface color; fade a BlendMode.DstIn gradient on an offscreen layer; blur draws the band's content again under graphicsLayer { renderEffect = BlurEffect(…) } with a gradient mask on API 31 and later, and shadow below it. | A SingleChildScrollView (or the product's scrollable via its ScrollController); ScrollMetrics.extentBefore/extentAfter, read in a NotificationListener<ScrollMetricsNotification>, tell the edges. shadow is a DecoratedBox gradient in the surface color; fade a ShaderMask with BlendMode.dstIn; blur BackdropFilter bands under ShaderMask. | A ScrollView; onScroll with scrollEventThrottle and the content size tell the edges, and the edge state is set only when it changes. shadow is a gradient view in the surface color where the product passes a gradient component, else a stack of translucent strips; fade needs a masked view the product passes, and is drawn as shadow without it. React Native has no blur of its own: blur is drawn only where the product passes a blur view component; otherwise shadow (SCA-9). |
Tokens
| Token | Aliases | Resolved (light) |
|---|---|---|
--tanrei-comp-scroll-area-blur-extent | sys.scroll-edge.blur.extent | 48px |
--tanrei-comp-scroll-area-blur-layers | sys.scroll-edge.blur.layers | 4 |
--tanrei-comp-scroll-area-blur-radius | sys.scroll-edge.blur.radius | 8px |
--tanrei-comp-scroll-area-fade-extent | sys.scroll-edge.extent | 24px |
--tanrei-comp-scroll-area-line-color | sys.color.outline-variant | |
--tanrei-comp-scroll-area-line-width | sys.border.hairline | 1px |
--tanrei-comp-scroll-area-motion-duration | sys.motion.role.state.default | 250ms |
--tanrei-comp-scroll-area-motion-easing | sys.motion.easing.state | cubic-bezier(0.2, 0, 0, 1) |
--tanrei-comp-scroll-area-scroll-edge | sys.behavior.scroll-edge | 0 |
--tanrei-comp-scroll-area-shadow-color | sys.color.surface | |
--tanrei-comp-scroll-area-shadow-extent | sys.scroll-edge.extent | 24px |
Fixtures
Canonical renderings. Every platform snapshots each fixture under the same id so the results can be compared.
default
label: Messages slots: default fade
scrollEdge: fade label: Messages slots: default line
scrollEdge: line label: Messages slots: default blur
scrollEdge: blur label: Messages slots: default none
scrollEdge: none label: Messages slots: default sideways
edges: ["start","end"] label: Photos slots: default rtl-sideways
edges: ["start","end"] label: Photos direction: rtl slots: default Generated from specs/scroll-area.spec.json, tokens/comp/scroll-area.tokens.json, design/tokens/
Use a scroll area where your layout gives a part of the screen a fixed size and its content can be longer: a list of messages beside a conversation, the results under a search field, a long form in a pane, a row of pictures that scrolls sideways. The area keeps the content where you put it and says, at each edge it watches, that more lies beyond.
You do not need one around a component that scrolls by itself — a table, a dialog’s content, a sheet — nor around the page: the page’s own scrolling has no edge to mark. A dialog, a sheet, a popover and an app bar draw their own line where a part that stays in place meets content that scrolls.
| Form | Use for |
|---|---|
shadow |
An opaque surface: the content sinks into it. The band is drawn in the color of the surface the area stands on, not in a gray of its own. It is the default system’s choice. |
fade |
A transparent surface, a picture or a video behind the area. The content itself fades out and no color is drawn, so what lies behind shows through. |
line |
A product that marks its edges with lines, and a dense layout where a band would cover too much of the content. The line is a hairline in the color of a divider. |
blur |
A product whose bars and edges are translucent: the content goes soft at the edge. It costs the most to draw (below). |
none |
A box whose edges are already plain, such as one whose scroll bar is always shown and is enough. |
Each edge is drawn by itself, and only while content lies beyond it: at the top of the list only the bottom edge is marked. An edge fades in and out as that changes, at once where motion is reduced. The mark never changes the area’s size and never moves the content.
edges names which edges are watched: top and bottom by default, and start and end for a row that scrolls sideways. Start is the left in a left-to-right layout and the right in a right-to-left one.
A shadow is a band of the surface’s own color laid over the content, full at the edge. On the surface its color names, it joins the surface with no seam; on any other it shows as a smear of the wrong color. comp.scroll-area.shadow.color is the plain surface (sys.color.surface) by default. Where the area stands on another surface — a card, a sheet, a container color — set it to that surface’s color: in a layer, for every scroll area that stands there, or on the one instance. On the web that is the --tanrei-comp-scroll-area-shadow-color custom property, set on the element or on an ancestor.
Where nothing opaque stands behind the area — a translucent panel, a picture, a video — no color is right. Choose fade there.
A blur draws the content in its band again, blurred, in every frame of a scroll: comp.scroll-area.blur.layers layers of a stepped radius (4 in the default system, up to a radius of 8 at the edge, in a band 48 deep). Use it where the product’s look asks for it, and keep it to at most two blurred edges on a screen — the top and bottom of one list, not every pane. Where the platform cannot blur what lies behind a band (a browser without backdrop filters, Android before 12, React Native without a blur view your product passes), the area draws shadow instead, so set the shadow’s color even where you choose a blur.
What marks a scrolling box’s edge is a choice of kind, made once for the product: its lists, forms and panes should not each mark their edges differently.
tanrei.sys.behavior.scroll-edge
What marks an edge of a box that scrolls while content lies beyond it, scrolled out of view past that edge. shadow: a band sys.scroll-edge.extent deep in the color of the surface the box stands on, full at the edge and none at the band's inner end, so that the content sinks into the surface. fade: the content itself fades out over the same depth toward the edge, so that whatever lies behind it — a transparent surface, a picture, a video — shows through. line: a hairline along the edge. blur: the content blurred in a band sys.scroll-edge.blur.extent deep, most at the edge. A platform that cannot blur what lies behind draws shadow, the first value; with a person's own forced colors every choice is drawn as the line. Read by the scroll area through its own component token, so that a design system can set it apart; an instance can set its own.
Generated from tokens/sys/behavior.tokens.json
The scroll area reads it through its own token, comp.scroll-area.scroll-edge, so a design system can set the scroll area apart from the system’s choice. One instance sets its own with scrollEdge (scroll-edge on the web); its default, auto, follows the tokens. The default system draws shadow; m3-like draws line and cupertino blur, as their originals mark their scrolling edges.
| Design system | scroll-edge |
|---|---|
tanrei | shadow |
cupertino | blur |
m3-expressive-like | line |
m3-like | line |
Generated from tokens/systems/*.system.json, design/tokens/<system>/tanrei.light.tokens.json
Two choices of the system concern scrolling, and they answer different questions:
sys.behavior.divider-visibilitysays when the line of a fixed region stands: the edge of an app bar, of a dialog’s header and actions, of a sheet’s header — a part that stays in place while content scrolls under it. It is drawn always, or only while something is scrolled beyond it.sys.behavior.scroll-edgesays what marks the edge of a box that scrolls, while content lies beyond that edge: a shadow, a fade, a line or a blur.
A product can set them independently: a dialog whose header line follows the scroll, and lists that sink into their surface beside it.
The scroll area is the platform’s own scroll box with marks drawn over its edges. Wheel, trackpad, touch, the keyboard, assistive technology and the platform’s scroll bars all work as they do in any other box, and the scroll bars keep the platform’s look. The area adds no scrolling of its own, no snapping and no scroll bar; it lays nothing out inside, and has no fill, edge or corner. Style the content as you would anywhere else.
- Give the area its size in your layout: a height, a share of a grid, the room left by a header and a footer. It takes the size it is given.
- Set the shadow’s color to the surface the area stands on, whenever that is not the plain surface.
- Give it a label that says what it holds: “Messages”, “Results”, “Photos”.
- Don’t draw a divider, a border or a gradient of your own at a scrolling edge. Choose the scroll edge instead, so that it appears only while content lies beyond the edge and matches the rest of the product.
- Don’t use a shadow over a picture, a video or a translucent surface. Use a fade.
- Don’t put more than two blurred edges on a screen.
- Don’t nest scroll areas that scroll in the same direction. A person cannot tell which one a swipe will move.
- Don’t hide the platform’s scroll bars to make room for the marks. The marks say that there is more; the scroll bar says how much, and is a control in its own right.
- Role
region, only while the box is a focus stop of its own (SCA-10); otherwise none- Labeling
- While the box is a focus stop it is a region named by label. The scroll edges are hidden.
- Minimum target
- The hit area meets the minimum target size even when the visual size is smaller. minimum 32px · pointer 44px · spacing 8px · touch 48px
Keyboard
| Keys | Action |
|---|---|
| Tab | Moves focus into the content, or to the box itself while nothing inside takes focus and the content does not fit. |
| Arrow keys, Page Up, Page Down, Home, End, Space | Scroll the box while it has focus, as the platform scrolls any scroll box. |
Notes
- Not interactive except as a scroll box: it has no target of its own, and its focus stop exists only so that a keyboard can scroll content that has nothing focusable (WCAG 2.1.1).
- Animation from interactions (WCAG 2.3.3): the scroll edge's fade is a change of opacity, not motion, and is still made at once where motion is reduced.
- A shadow or a fade lowers the contrast of the content it lies over, by design, only within its band and only while that content is scrolled toward the edge; the content is read at full contrast once it is scrolled into view.
Generated from specs/scroll-area.spec.json, tokens/sys/measure.tokens.json
- While its content does not fit and nothing inside takes keyboard focus, the box itself becomes one stop in the focus order, exposed as a region named by
label, so that a keyboard can scroll it (WCAG 2.1.1). The arrow keys, Page Up, Page Down, Home, End and Space scroll it, as the platform scrolls any box. - While something inside takes focus, or the content fits, the box is no focus stop and exposes no role: the keyboard reaches the content, and the content scrolls into view as it is focused.
- The focus indicator is drawn inside the box’s edge, above every mark and never faded by one, and only for keyboard focus.
- The marks are hidden from assistive technology, and every press, hover and scroll over them reaches the content under them.
- An edge’s mark fades in and out over a short time, a change of opacity and not a motion; it appears at once where reduced motion is requested.
- With forced colors, every form is drawn as a line in the text color.
- It has no words of its own. An empty label while the box is a focus stop, and an unknown
scrollEdgeoredgesvalue, are reported in debug builds.
- Give it a
labelthat says what it holds. A person who tabs to the box hears that name; without one they hear only that there is a region. - Expect content under a band to be read once it scrolls into view, not where it is. A shadow or a fade lowers the contrast of the content under it, by design, but only inside its band and only while that content is scrolled toward the edge; the content is at full contrast once it is scrolled into view.
- Keep content that changes on its own (a live list, new messages) announced the way you would anywhere else. The area does not announce what scrolls in.