Skip to content

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.

Before you start

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.

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.

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.

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.

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.

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

NameTypeDefaultDescriptionVersion
guttersPositionsticky | absolutestickyWhere 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
orientationvertical | horizontal | bothverticalThe directions the area scrolls in, each with its own scrollbar. Content too wide for a vertical area is cut off.Unreleased
triggerhover | scroll | nonehoverhover 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
hideDelaynumber600How long the scrollbars stay after scrolling stops, in ms. With trigger="scroll" it is at least 100.Unreleased
sizesmall | mediummediumThumb thickness: 5px or 7px, 3px more on hover.Unreleased
fadebooleanfalseFade the content out toward each edge that has more past it. The scrollbars don’t fade.Unreleased
overscrollnone | contain | autononenone 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 }undefinedRoom 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
actionsRefRef<ScrollAreaActions>undefinedGets 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 }) => voidundefinedCalled when the area reaches or leaves an edge (true: scrolled all the way to it), and after mounting when the content overflows.Unreleased
classNamestringundefinedClass of the root: the container (sticky) or the frame (absolute). Size and frame the area here.Unreleased
styleCSSPropertiesundefinedStyle of the root.Unreleased
rootRefRef<HTMLDivElement>undefinedThe root: the container itself (sticky) or the frame (absolute).Unreleased
containerClassNamestringundefinedClass of the area’s own container; with sticky the same element as the root.Unreleased
containerStyleCSSPropertiesundefinedStyle of the area’s own container.Unreleased
contentClassNamestringundefinedClass of the element that wraps children.Unreleased
contentStyleCSSPropertiesundefinedStyle of the element that wraps children.Unreleased
onScroll(event: UIEvent<HTMLDivElement>) => voidundefinedCalled on every scroll of the container.Unreleased
childrenReactNodeundefinedThe scrolling content.Unreleased

scrollToElement Options

NameTypeDefaultDescriptionVersion
blockstart | center | end | neareststartWhere 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
offsetnumber0Px kept clear between the element and the edge it lines up with, such as a sticky header’s height. center ignores it.Unreleased
behaviorScrollBehaviorundefinedsmooth 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

NameTypeDefaultDescriptionVersion
triggerhover | scroll | nonehoverAs on ScrollArea.Unreleased
hideDelaynumber600As on ScrollArea.Unreleased
sizesmall | mediummediumAs on ScrollArea.Unreleased
overscrollnone | contain | autononeAs on ScrollArea.Unreleased
wrapperClassNamestringundefinedClass of the frame that holds the textarea and its scrollbar. Put the border and background here.Unreleased
wrapperStyleCSSPropertiesundefinedStyle 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:

NameTypeDefaultDescriptionVersion
guttersPositionsticky | absolutestickyWhere 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
containerRefRef<E>undefinedYour ref to the element that scrolls; containerProps.ref forwards to it at commit.Unreleased
frameRefRef<HTMLDivElement>undefinedWith absolute gutters, your ref to the frame; frameProps.ref forwards to it.Unreleased
contentRefRefObject<HTMLElement | null>undefinedAn 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
fadeRefRefObject<HTMLElement | null>undefinedWith fade and sticky gutters, the content element (class p-scroll-area__content) the mask goes on.Unreleased

useScrollAreaContainer Result

NameTypeDescriptionVersion
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 } | undefinedWith absolute gutters, spread on the frame; undefined with sticky gutters (typed as always there when you pass guttersPosition: "absolute").Unreleased
guttersPropsScrollAreaGuttersPropsSpread on <ScrollAreaGutters />.Unreleased
guttersPositionsticky | absoluteWhere to put the gutters.Unreleased
measure() => voidMeasures again now, as actionsRef.measure().Unreleased
scrollToElement(element, options?) => voidAs on actionsRef.Unreleased
scrollablebooleanWhether 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.