Scroller
A focusable overflow region for horizontal rails, vertical feeds, and bidirectional canvases.
Use Scroller when a bounded collection intentionally extends beyond its visible region. Use Pagination for discrete result pages and a virtualization system for very large feeds.
Installation
The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/scroller.tsx.
Usage
<Scroller
overflow="x"
ariaLabel="Featured projects"
childrenContainerClassName="gap-3 p-1"
>
{projects.map((project) => (
<Card key={project.id} className="w-52 shrink-0">
<CardContent>{project.name}</CardContent>
</Card>
))}
</Scroller>Horizontal children need a stable width and shrink-0. Apply rail gaps and padding through childrenContainerClassName so they move with the content.
Examples
Vertical feed
Vertical scrolling requires a bounded height. Its overlay scrollbar appears during hover or scrolling while edge fades indicate additional content.
API reference
| Prop | Type | Default | Description |
|---|---|---|---|
| overflow | "x" | "y" | "both" | "x" | Selects horizontal, vertical, or bidirectional scrolling. |
| height / width | number | string | - / "100%" | Sets bounded dimensions using pixels or CSS lengths. |
| fade / fadeWidth | boolean / number | true / 32 | Controls directional edge masks and their pixel width. |
| childrenContainerClassName | string | - | Styles the moving inner content wrapper. |
| ariaLabel | string | - | Names the focusable scroll region. |
Horizontal mode hides its scrollbar and relies on edge fades plus native touch or trackpad movement. Vertical and bidirectional modes render an overlay vertical scrollbar. Fades are not applied in both mode.
Accessibility
- Give every Scroller a concise
ariaLabel, especially when no visible heading clearly identifies the region. - The viewport is focusable. Arrow keys scroll it using native browser behavior.
- Interactive children retain normal DOM tab order even when some content begins outside the visible region.
- Do not hide essential actions exclusively beyond an unannounced horizontal edge.
- Preserve touch targets and enough spacing between interactive rail items.