CustomScroll is a scroll region with a themed scrollbar. Content scrolls natively — wheel, touch, keyboard,
assistive tech — while the platform bar is hidden and a thin thumb is drawn over the content. Always bound it with
height, maxHeight or a sized flex slot; an unbounded region grows with its content and never scrolls.
Layout & Surfaces
Use when
- A region scrolls inside the page — a surface body, side panel, picker list or log — instead of
overflowY: 'auto'.
- You need a horizontal strip (
axis="x") or a wide table or code block (axis="both").
Avoid when
- The page itself scrolls — let the
body scroll natively.
- The list is very large — virtualize it and point the virtualizer at
scrollableRef.
Put the cap on CustomScroll, not overflowY on the surface. The thumb shows on hover, focus, scroll and drag;
thumb="always" keeps it visible whenever the content overflows. Drag it, or press the rail to page.
1. Long list — scrolls past the cap.2. Long list — scrolls past the cap.3. Long list — scrolls past the cap.4. Long list — scrolls past the cap.5. Long list — scrolls past the cap.6. Long list — scrolls past the cap.7. Long list — scrolls past the cap.8. Long list — scrolls past the cap.9. Long list — scrolls past the cap.10. Long list — scrolls past the cap.11. Long list — scrolls past the cap.12. Long list — scrolls past the cap.13. Long list — scrolls past the cap.14. Long list — scrolls past the cap.15. Long list — scrolls past the cap.16. Long list — scrolls past the cap.17. Long list — scrolls past the cap.18. Long list — scrolls past the cap.19. Long list — scrolls past the cap.20. Long list — scrolls past the cap.21. Long list — scrolls past the cap.22. Long list — scrolls past the cap.23. Long list — scrolls past the cap.24. Long list — scrolls past the cap.25. Long list — scrolls past the cap.26. Long list — scrolls past the cap.27. Long list — scrolls past the cap.28. Long list — scrolls past the cap.29. Long list — scrolls past the cap.30. Long list — scrolls past the cap.
<Paper p="small">
<CustomScroll maxHeight="200px" cq={{ lg: { maxHeight: '480px' } }}>
{items}
</CustomScroll>
</Paper>Section 1Section 2Section 3Section 4Section 5Section 6Section 7Section 8Section 9Section 10Section 11Section 12Section 13Section 14Section 15Section 16
<CustomScroll axis="x">
<Flex flexDirection="row" gap="small">
{chips}
</Flex>
</CustomScroll>Inside a padded surface the thumb rides the region's edge, a full padding away from the surface edge. Pass the
surface's padding token to bleed: the region is pulled out on the inline-end side and padded back, so the text keeps
its inset while the thumb sits at the edge. No ancestor between the region and the surface may clip on the inline
axis, or the bleed is cut off. Modal and Sheet bodies use bleed="large" with overscroll="contain".
1. With bleed — thumb at the edge.2. With bleed — thumb at the edge.3. With bleed — thumb at the edge.4. With bleed — thumb at the edge.5. With bleed — thumb at the edge.6. With bleed — thumb at the edge.7. With bleed — thumb at the edge.8. With bleed — thumb at the edge.9. With bleed — thumb at the edge.10. With bleed — thumb at the edge.11. With bleed — thumb at the edge.12. With bleed — thumb at the edge.13. With bleed — thumb at the edge.14. With bleed — thumb at the edge.15. With bleed — thumb at the edge.16. With bleed — thumb at the edge.17. With bleed — thumb at the edge.18. With bleed — thumb at the edge.19. With bleed — thumb at the edge.20. With bleed — thumb at the edge.21. With bleed — thumb at the edge.22. With bleed — thumb at the edge.23. With bleed — thumb at the edge.24. With bleed — thumb at the edge.25. With bleed — thumb at the edge.26. With bleed — thumb at the edge.27. With bleed — thumb at the edge.28. With bleed — thumb at the edge.29. With bleed — thumb at the edge.30. With bleed — thumb at the edge.
<Paper p="large">
<CustomScroll maxHeight="320px" bleed="large">
{entries}
</CustomScroll>
</Paper>overscroll="contain" stops a scroll that reaches the end from moving the page behind — use it in dialogs, sheets
and drawers.
- The inner scroller is focusable (
tabIndex={0}), so a region without interactive content still scrolls with the
arrow keys.
- Name it through
scrollerProps (role, aria-label, aria-labelledby, id); these land on the focused node,
not on the root.
- The rail and thumb are
aria-hidden.
<CustomScroll maxHeight="320px" scrollerProps={{ role: 'region', 'aria-label': 'Activity log' }}>
{entries}
</CustomScroll>Name
Type
Default
Description
axis
'y'
Axis that scrolls. `'y'` clips horizontal overflow; `'x'` is a
horizontal strip (chips, a tab row); `'both'` draws a thumb per
overflowing axis (wide tables, code).
bleed
"small""zero""micro""xs""medium""large""xl""xxl""giant"
none
Pulls the region out by this spacing token on the inline-end side — the
side the vertical thumb rides — and pads the scroller back by the same
amount, so the content keeps its alignment while the thumb sits at the
surface edge instead of inside its padding. Pass the padding token of
the surface around the region (a `Modal` / `Sheet` body bleeds
`'large'`). Every ancestor between the region and that surface must not
clip on the inline axis (no `overflow: hidden`), or the bleed is cut off.
color
string
none
Theme token (`theme.colors`) used as `color`. Has lower precedence than
`contrast`: when both are provided, the contrast calculation wins.
Stays `string` (not the typed union): `color` is also an HTML attribute
(`<li color>`, etc.) and interfaces extending native props require
identical types on the name collision.
containment
string
none
Containment marker for the `cq` channel: emits
`container-type` (+ `container-name` when the string form carries one,
e.g. `'inline-size card'`). Apply on the immediate wrapper of the
adapting component — NEVER on page-level shells.
legibility
"on-photo"
none
Reading-shadow preset for text over a photographic background
(`on-photo`). Replaces the inline `style={{ textShadow }}` in the
consumer (brasil_2030 radar, gap A3). Token emission is deferred until a
2nd consumer asks for the raw var (see backlog).
lineClamp
number
none
Caps the text at this many lines and ends the cut with an ellipsis.
The full string stays in the DOM.
overscroll
'auto'
Scroll chaining at the ends of the region. `'contain'` stops a scroll
that reaches the end from moving the page behind — for dialogs, sheets
and drawers.
pageShell
boolean
none
Centers the element and caps the width at `theme.layout.pageMaxWidth`.
The page shell of a classic centered layout.
readable
none
Makes the `color` legible against the page surface: `true` = WCAG AA
(4.5), a number sets a custom floor. Ignored with `contrast`.
See the Layout Props concept page for the full semantics.
scrollableRef
Ref<HTMLDivElement>
none
Ref to the inner node that actually scrolls — what virtualizers need
as their scroll element (the outer `ref` is the clipped container).
scrollerProps
ScrollerA11yProps
none
Accessibility attributes for the inner scroller — the node that takes
keyboard focus (`tabIndex={0}`). Name a region that holds no
interactive content, e.g. `{ role: 'region', 'aria-label': 'Invoices' }`;
on the root they would name a node that is never focused.
thumb
'auto'
Thumb visibility. `'auto'` reveals it on hover, keyboard focus, while
scrolling and while dragging; `'always'` keeps it shown whenever the
content overflows — a cue that the region scrolls.
transform
string
none
CSS `transform` value (e.g. `translate(-50%, -33px)`). Never leaks
to the DOM as an attribute.
Layout props land on the outer clipped root; onScroll and scrollableRef attach to the inner scroller. See
Layout Props.