ScrollArea
Use ScrollArea for any box whose content scrolls inside the page, such as a sidebar, a panel, a code view or a chat log, when you want thin scrollbars that look the same on every platform. For thousands of rows, use VirtualList, which can show the same scrollbar; Layout already scrolls its panes in one.
Give the scroll area a height or a max-height. Without one it grows with its content and never scrolls.
ScrollArea is a scrolling box with thin overlay scrollbars in the style of macOS: a rounded thumb that fades in while you scroll or hover, thickens when you point at it (there is no visible track), and fades out shortly after scrolling stops. It looks the same in every theme and on every platform. Scrolling itself stays native, so the wheel, trackpad, touch and keyboard work as usual; the thumb can also be dragged, and pressing the empty space beside it pages.
It follows react-scroll-area-demo: the area measures a container, the element that scrolls, and draws the gutters (ScrollAreaGutters, the scrollbars) where guttersPosition says. With sticky gutters, the default, the gutters are a zero-height first child of the container, and the container is the whole area: one element. With absolute gutters a frame holds the container and the gutters beside it. ScrollArea is the common case, with a div of its own as the container; for an element you render yourself (a list, VirtualList’s scroller), call useScrollAreaContainer and spread what it returns on your elements.
#Demos
#Basic
Give the scroll area a height (or a max-height). Put padding on the content with contentClassName or contentStyle, not on the scroll area itself, so the scrollbars stay at the edges.
#Orientation
orientation sets the directions the area scrolls in: vertical (the default; content too wide is cut off), horizontal or both, each with its own scrollbar. When both directions overflow, each scrollbar stops short of the corner, and the corner stays transparent.
| Kate | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Kirby | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Mika | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Noor | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Oskar | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Priya | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Quinn | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Rae | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
| Sol | Sep 1 | Sep 2 | Sep 3 | Sep 4 | Sep 5 | Sep 6 | Sep 7 | Sep 8 | Sep 9 | Sep 10 | Sep 11 | Sep 12 | Sep 13 | Sep 14 | Sep 15 | Sep 16 | Sep 17 | Sep 18 | Sep 19 | Sep 20 | Sep 21 |
#Trigger
By default the scrollbars show while the pointer is over the area and while it scrolls. trigger="none" keeps them visible.
#Show only while scrolling
trigger="scroll" shows the scrollbars only while the area scrolls (or a thumb is dragged), not on hover; while hidden they don’t catch presses meant for the content. A scrollbar the pointer is already on stays visible and usable until the pointer leaves it. With every trigger, hideDelay sets how long they stay after scrolling stops: 600ms by default, and at least 100ms with trigger="scroll".
#Size
size sets the thumb thickness: small is 5px and medium 7px. Both grow by 3px while the scrollbar is pointed at or the thumb is dragged.
#Fade
fade fades the content out toward each edge that has more content past it, over up to 24px, so the fade grows in as the content leaves an edge. Only the content fades, never the scrollbars; with orientation="both" the two directions combine. The fade is a mask that repaints the content while it scrolls, so use it on short areas rather than long lists.
#Edge state
While there is more content past an edge, the scroll area has a modifier class for it: p-scroll-area--overflow-y-start (above), --overflow-y-end (below), --overflow-x-start and --overflow-x-end (the inline start and end, so the right and left edges in right-to-left layouts). Style shadows, dividers or “more” hints from them. Scrolling renders nothing: these classes, --scrolling and --dragging are set on the root directly (and set again when a render replaces its className), and nothing is written on the root while it scrolls (with fade, only the mask moves). The area re-renders only when a scrollbar appears or disappears.
The thumbs behave like native scrollbars: each frame, a thumb’s length and place follow the current scroll and content size, with no transition. Where the browser has scroll-driven animations, the browser itself moves the thumbs on the compositor, from the container’s own named scroll timeline (an area nested in another’s container takes its own); the script only sizes them when a size changes. Elsewhere a scroll asks for one animation frame, however many scroll events arrive, which moves each thumb with a transform. The area watches the container, the content and each gutter with a ResizeObserver; actionsRef.measure() measures again for a change nothing observed reports.
onEdgeChange is called with { top, bottom, left, right } (true when the area is scrolled all the way to that edge) whenever one of them flips, and right after mounting when the content overflows.
A header or footer stuck inside the area (position: sticky) covers the ends of the scroll area, so give its height to railInset: railInset={{ top: 40, bottom: 40 }} starts the vertical scrollbar below the header and ends it above the footer. left and right do the same for the horizontal scrollbar, such as beside a sticky first column. The same room can come from CSS instead, set on the area itself: --p-scroll-area-rail-inset-top, -bottom, -left and -right (they don’t inherit, so a scroll area nested inside doesn’t take them).
#Overscroll
By default (overscroll="none"), a scroll that reaches the end of the area stops there: it neither carries on to the page behind it nor bounces the area (and its sticky header or footer) on Mac trackpads and iOS. overscroll="contain" also stops it there but lets those devices bounce the area at its edges. overscroll="auto" carries the scroll on to the page, like a plain scrolling div. none and contain hold only in a direction where the area’s content overflows right now, so an area that only overflows sideways never stops the page from scrolling down.
#Scrolling from code
ref is the container, the element that scrolls (with sticky gutters, the default, it is the root too), so it gets the native scrollTo and scrollBy, and onScroll receives its scroll events.
Section 1
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 2
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 3
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 4
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 5
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 6
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 7
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 8
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 9
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 10
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 11
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
Section 12
The scroll area is the scrolling element, so its ref has the native scrollTo and scrollBy.
#Scrolling to an element
actionsRef gets scrollToElement(element, options), which scrolls the area, and only the area (scrollIntoView would scroll the page too), so that an element inside it is in view. block lines the element up at the start (the default), center or end, or nearest scrolls only as far as needed. offset keeps that many px clear between the element and the edge, such as the height of a sticky header (give the same height to railInset so the scrollbar starts below it too); behavior: "smooth" animates the scroll. ref still points at the container.
Chapter 1
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 2
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 3
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 4
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 5
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 6
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 7
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
Chapter 8
scrollToElement scrolls only the area, never the page, and keeps the sticky header clear with offset.
#Textarea
A <textarea> scrolls itself and can’t hold children, so ScrollAreaTextarea is useScrollAreaContainer with absolute gutters whose container is a native textarea: a frame holds the textarea and lays the same scrollbar over it. Frame the wrapper (wrapperClassName: border, background, focus ring) and pad the textarea (className); the scrollbar follows typing, pasting and a controlled value. Drag the bottom corner to make the textarea taller; the scrollbar stops above the grip so it stays reachable.
#Gutters position
guttersPosition="sticky" (the default) adds the least: the area is one element, the gutters a zero-height layer inside it that takes no room, so ref, className, style and the native props are all on the element that scrolls. guttersPosition="absolute" puts nothing inside the container: a frame (the root) holds it, and the gutters lie over the frame. className and style then size and frame the frame (its size includes its border), and ref, onScroll, tabIndex and the other native props go to the container (containerClassName, containerStyle); rootRef is the root either way. With absolute gutters the fade mask is on the container and the focus ring goes around the frame.
#Your own container
useScrollAreaContainer(options) is ScrollArea without its div: call it in the component that renders the element that scrolls, and spread what it returns. It takes ScrollArea’s options (guttersPosition, orientation, trigger, size, fade, overscroll, railInset, hideDelay, onEdgeChange, actionsRef), contentRef, and your own refs to the element (containerRef) and the frame (frameRef). Put containerProps on the element that scrolls (its className before yours, its style with yours after it) and give the element its overflow yourself; render <ScrollAreaGutters {...guttersProps} /> as its first child with sticky gutters. The hook listens to the element’s scroll itself, and binds again when a render puts another element in ref.
- Kate
- Kirby
- Mika
- Noor
- Oskar
- Priya
- Quinn
- Rae
- Sol
- Tove
With guttersPosition: "absolute", spread frameProps on a frame you render around the element and the gutters, and put <ScrollAreaGutters {...guttersProps} /> right after the element. The frame is a flex column: give the element flex: 1 1 auto and min-height: 0 so it fills the frame and scrolls.
- Release 1.24.0
- Release 1.23.0
- Release 1.22.0
- Release 1.21.0
- Release 1.20.0
- Release 1.19.0
- Release 1.18.0
- Release 1.17.0
- Release 1.16.0
- Release 1.15.0
- Release 1.14.0
- Release 1.13.0
- Release 1.12.0
- Release 1.11.0
- Release 1.10.0
- Release 1.9.0
- Release 1.8.0
- Release 1.7.0
- Release 1.6.0
- Release 1.5.0
- Release 1.4.0
- Release 1.3.0
- Release 1.2.0
- Release 1.1.0
#Over a VirtualList
VirtualList renders its own scroller, so it takes the scrollbars this way: the list’s domRef gets containerProps.ref, its className and style take the container’s, and the sticky gutters go in through its header, the scroller’s first child. The list still scrolls, measures and anchors itself. With overscroll: "auto" the list keeps its own overscroll-behavior.
#Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
guttersPosition | sticky | absolute | sticky | Where the scrollbars go: a zero-height layer inside the container, which is the root (sticky), or beside it, laid over a frame that holds both (absolute). | Unreleased |
orientation | vertical | horizontal | both | vertical | The directions the area scrolls in, each with its own scrollbar. Content too wide for a vertical area is cut off. | Unreleased |
trigger | hover | scroll | none | hover | hover shows the scrollbars while the pointer is over the area; scroll only while it scrolls; none always shows them. They always show while scrolling or dragging. | Unreleased |
hideDelay | number | 600 | How long the scrollbars stay after scrolling stops, in ms. With trigger="scroll" it is at least 100. | Unreleased |
size | small | medium | medium | Thumb thickness: 5px or 7px, 3px more on hover. | Unreleased |
fade | boolean | false | Fade the content out toward each edge that has more past it. The scrollbars don’t fade. | Unreleased |
overscroll | none | contain | auto | none | none stops a scroll that reaches the end there, with no bounce; contain stops it but lets Mac trackpads and iOS bounce the area; auto lets it carry on to the page. In each direction that overflows. | Unreleased |
railInset | { top?: number; bottom?: number; left?: number; right?: number } | undefined | Room in px the scrollbars keep clear at each end, such as a sticky header’s height. top and bottom shorten the vertical scrollbar, left and right the horizontal one. | Unreleased |
actionsRef | Ref<ScrollAreaActions> | undefined | Gets scrollToElement(element, { block?, offset?, behavior? }), which scrolls only the area so that element is in view, and measure(), which measures again for a size change nothing observed reports. | Unreleased |
onEdgeChange | (edges: { top: boolean; bottom: boolean; left: boolean; right: boolean }) => void | undefined | Called when the area reaches or leaves an edge (true: scrolled all the way to it), and after mounting when the content overflows. | Unreleased |
className | string | undefined | Class of the root: the container (sticky) or the frame (absolute). Size and frame the area here. | Unreleased |
style | CSSProperties | undefined | Style of the root. | Unreleased |
rootRef | Ref<HTMLDivElement> | undefined | The root: the container itself (sticky) or the frame (absolute). | Unreleased |
containerClassName | string | undefined | Class of the area’s own container; with sticky the same element as the root. | Unreleased |
containerStyle | CSSProperties | undefined | Style of the area’s own container. | Unreleased |
contentClassName | string | undefined | Class of the element that wraps children. | Unreleased |
contentStyle | CSSProperties | undefined | Style of the element that wraps children. | Unreleased |
onScroll | (event: UIEvent<HTMLDivElement>) => void | undefined | Called on every scroll of the container. | Unreleased |
children | ReactNode | undefined | The scrolling content. | Unreleased |
#scrollToElement Options
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
block | start | center | end | nearest | start | Where the element lines up. In a horizontal area this is the horizontal axis, and start is the inline start; with both, the horizontal axis scrolls only as far as needed. | Unreleased |
offset | number | 0 | Px kept clear between the element and the edge it lines up with, such as a sticky header’s height. center ignores it. | Unreleased |
behavior | ScrollBehavior | undefined | smooth animates the scroll, as in scrollTo. | Unreleased |
ScrollArea also accepts native div attributes and a ref, which go to the container, the element that scrolls; use its own scrollTo and scrollBy for offsets, and actionsRef to scroll to an element. orientation, trigger, hideDelay, size, fade and overscroll can be set for every scroll area (and every useScrollAreaContainer) through ConfigProvider’s componentOptions.ScrollArea; a prop wins over it. The class names are built from clsPrefix. When there is something to scroll, the area is focusable (tabIndex={0}) so keyboard users can scroll it with the arrow keys; give it an aria-label that says what it contains. The custom scrollbars are hidden from assistive technology, which uses the native scrolling instead.
#ScrollAreaTextarea Props
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
trigger | hover | scroll | none | hover | As on ScrollArea. | Unreleased |
hideDelay | number | 600 | As on ScrollArea. | Unreleased |
size | small | medium | medium | As on ScrollArea. | Unreleased |
overscroll | none | contain | auto | none | As on ScrollArea. | Unreleased |
wrapperClassName | string | undefined | Class of the frame that holds the textarea and its scrollbar. Put the border and background here. | Unreleased |
wrapperStyle | CSSProperties | undefined | Style of the frame. | Unreleased |
Every other prop, including ref, className, style, value and onScroll, goes to the native textarea.
#useScrollAreaContainer Options
ScrollArea’s orientation, trigger, hideDelay, size, fade, overscroll, railInset, actionsRef and onEdgeChange, defaulting to ConfigProvider’s componentOptions.ScrollArea as on ScrollArea, and:
| Name | Type | Default | Description | Version |
|---|---|---|---|---|
guttersPosition | sticky | absolute | sticky | Where you render the gutters: the container’s first child, or right after it in a frame. Not taken from ConfigProvider, since it decides what you render. | Unreleased |
containerRef | Ref<E> | undefined | Your ref to the element that scrolls; containerProps.ref forwards to it at commit. | Unreleased |
frameRef | Ref<HTMLDivElement> | undefined | With absolute gutters, your ref to the frame; frameProps.ref forwards to it. | Unreleased |
contentRef | RefObject<HTMLElement | null> | undefined | An element whose size is the content’s, watched for size changes. Without it each element child of the container is watched, and children added or removed. | Unreleased |
fadeRef | RefObject<HTMLElement | null> | undefined | With fade and sticky gutters, the content element (class p-scroll-area__content) the mask goes on. | Unreleased |
#useScrollAreaContainer Result
| Name | Type | Description | Version |
|---|---|---|---|
containerProps | { ref, className, style, tabIndex } | Spread on the element that scrolls. With sticky gutters className and style are the root’s classes and variables; tabIndex is 0 while there is something to scroll. | Unreleased |
frameProps | { ref, className, style } | undefined | With absolute gutters, spread on the frame; undefined with sticky gutters (typed as always there when you pass guttersPosition: "absolute"). | Unreleased |
guttersProps | ScrollAreaGuttersProps | Spread on <ScrollAreaGutters />. | Unreleased |
guttersPosition | sticky | absolute | Where to put the gutters. | Unreleased |
measure | () => void | Measures again now, as actionsRef.measure(). | Unreleased |
scrollToElement | (element, options?) => void | As on actionsRef. | Unreleased |
scrollable | boolean | Whether either axis has something to scroll now. | Unreleased |
Everything it returns is stable until something it draws from changes, so it can go in a memoized child’s props. ScrollAreaGutters takes only guttersProps; it is hidden from assistive technology.