Skip to the content

CustomScroll

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

When to use

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.

Usage

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>

Horizontal strip

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>

Thumb at the surface edge

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.

Accessibility

  • 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>

Properties

Layout props land on the outer clipped root; onScroll and scrollableRef attach to the inner scroller. See Layout Props.

See also