ScrollArea
Scroll native content with styled scrollbars, edge shadows, and optional virtualization.
Anatomy#
Usage#
Use ScrollArea to constrain overflowing content. Scrolling stays native: wheel, touch, keyboard,
and scroll anchoring behave as in any scroll container. ScrollArea hides the native scrollbar and
draws its own over the content. When the area is a landmark of its own, label it with
role="region" and aria-label.
Structure and sizing#
Set a height or maximum height on the root for vertical scrolling and a width for horizontal
scrolling. The root positions the scrollbars; the viewport scrolls; the content wraps the
children. Put content layout such as flex and gap on classes.content, not on the root.
class, style, ref, and other attributes such as role and aria-label go to the root.
onScroll and tabIndex go to the viewport, and viewportRef receives it. The viewport joins
the tab order while its content overflows and leaves it when the content fits; pass tabIndex to
override this.
Orientation#
orientation selects the scrollable axes: vertical (default), horizontal, or both. With
both, the two scrollbars meet at the corner. Horizontal and two-axis content grows to its
natural width.
Scrollbars#
scrollbar selects how scrollbars appear:
| Value | Behavior |
|---|---|
auto |
Custom scrollbars while an axis overflows. This is the default. |
always |
Custom scrollbars at all times, even when content fits. |
hover |
Custom scrollbars while the pointer is over the area or it scrolls. |
scroll |
Custom scrollbars while the area scrolls. |
native |
Browser scrollbars. |
hidden |
No scrollbars; wheel, touch, and keyboard scrolling still work. |
hover and scroll scrollbars stay visible for scrollHideDelay milliseconds (default 600)
after activity ends. Drag the thumb to scroll, or press the track to jump to that position.
Scrollbars are hidden from assistive technology; keyboard scrolling goes through the focusable
viewport.
Edge shadows#
Set shadow to fade content out at edges that have more content beyond them. The shadow grows with
the remaining distance up to shadowSize pixels (default 40), so it appears gradually instead of
switching on. The mask fades content into the background behind the container.
Overflow state#
onOverflowChange receives { x: { start, end }, y: { start, end } } whenever the edges with
more content beyond them change. start and end are logical: in RTL content, the x start
edge is on the right. scrollThreshold sets how close to an edge, in pixels, scrolling counts as
reaching it.
onTopReached, onBottomReached, onLeftReached, and onRightReached fire once each time scrolling
reaches a physical edge (within scrollThreshold) of an overflowing axis; in RTL content
onLeftReached and onRightReached follow the physical edges, not the logical start/end. They
do not fire for the initial position. Combine onBottomReached with scrollThreshold to load more
content before the end.
setController receives a controller once, during setup. It holds the reactive overflow state and
scrollToEdge(axis, edge, options). Store it and call scrollToEdge after mount: the viewport does
not exist during setup, so an earlier call does nothing.
Virtualization#
Pass items and an itemRender component to render a collection; itemRender replaces children,
and items has no effect without it. itemRender is mounted as a component, so read props.item
and props.index lazily instead of destructuring them. Add a virtualizer from
createListVirtualizer() to render only the visible items; the viewport is its scroll container.
Spread props.rowProps on each row so the virtualizer can position and measure it. Create the
virtualizer with horizontal for orientation="horizontal".
Data attributes and CSS variables#
The root carries data-orientation, data-overflow-x and data-overflow-y while an axis
overflows, data-overflow-{x,y}-{start,end} for each overflowing edge, data-scrolling, and
data-hovering. Each scrollbar carries data-orientation, data-visible, data-dragging, and
data-corner while the corner is shown; the corner carries data-visible.
The root also exposes the remaining scroll distance of each edge in pixels as
--scroll-area-overflow-x-start, --scroll-area-overflow-x-end,
--scroll-area-overflow-y-start, and --scroll-area-overflow-y-end. Use them for custom
edge effects.
Theme and instance overrides#
Set scrollArea.defaultVariants to choose the scrollbar mode or enable shadows across a provider;
scrollbar: 'native' restores browser scrollbars everywhere. The recipe exposes
--scroll-area-shadow-size and the mask layers --scroll-area-shadow-y and
--scroll-area-shadow-x.
The shadow size resolves in this order, highest first: root style, styles.root, an explicit
shadowSize, then recipe and Theme defaults.
Examples#
Shadow overflowing activity#
Enable shadow on a vertical activity feed so clipped updates are visible at the edge.
Scroll project milestones#
Set orientation="horizontal" for a timeline. dir="rtl" scrolls from the right edge, and the
shadows follow the logical edges.
Scroll a wide table#
Set orientation="both" for content that overflows in both directions.
Jump to the latest notification#
Read onOverflowChange to show whether more notifications are hidden, and call
scrollToEdge from the controller.
Load more at the end#
onBottomReached with scrollThreshold requests the next page shortly before the end.
Virtualize a long log#
items, itemRender, and virtualizer render 10,000 lines while mounting only the visible ones.
API Reference#
Attributes#
data-hoveringdata-orientationdata-overflow-xdata-overflow-x-enddata-overflow-x-startdata-overflow-ydata-overflow-y-enddata-overflow-y-startdata-scrollingdata-cornerdata-draggingdata-visibleProps#
Renders a <div> element by default.