Stable in React

Scroll Area

A native scroll container with custom scrollbars.

Loading React 19.3.1…

Hover a part or use it. The code follows. · Loading React…

312Tests passing in React · 0 failing

10.2 KiBSize

Not measured yetMemory

Not measured yetSpeed

productdevbook and 18 upstream authors7 commits · last Nov 4

Install#

One package per framework. Scroll Area's parts come from it; the anatomy tab at the top shows how they nest.

bun add @▢▢▢▢/react

Six parts. The example uses five of them; the data does not say which are required.

ScrollArea.RootGroups all parts of the scroll area.
ScrollArea.ViewportThe actual scrollable container of the scroll area.
ScrollArea.ContentA container for the content of the scroll area.
ScrollArea.ScrollbarA vertical or horizontal scrollbar for the scroll area.
ScrollArea.ThumbThe draggable part of the scrollbar that indicates the current scroll position.
ScrollArea.CornerA small rectangular area that appears at the intersection of horizontal and vertical scrollbars. Not in the example.

Examples#

Common ways to put it to work. Each one runs live.

Two scrollbars, with Corner where they meet.

ScrollAreaBoth.tsx

Styling and accessibility#

The parts ship no styles. Style their states with these attributes; the CSS tab at the top has a sheet. The same CSS works in all five frameworks.

[data-scrolling]Present when the user scrolls inside the scroll area. On Root, Viewport, Content, Scrollbar, Thumb.
[data-has-overflow-x]Present when the scroll area content is wider than the viewport. On Root, Viewport, Content, Scrollbar.
[data-has-overflow-y]Present when the scroll area content is taller than the viewport. On Root, Viewport, Content, Scrollbar.
[data-overflow-x-start]Present when there is overflow on the horizontal start side. On Root, Viewport, Content, Scrollbar.
[data-overflow-x-end]Present when there is overflow on the horizontal end side. On Root, Viewport, Content, Scrollbar.
[data-overflow-y-start]Present when there is overflow on the vertical start side. On Root, Viewport, Content, Scrollbar.
[data-overflow-y-end]Present when there is overflow on the vertical end side. On Root, Viewport, Content, Scrollbar.
--scroll-area-corner-heightThe scroll area's corner height. On Root.
--scroll-area-corner-widthThe scroll area's corner width. On Root.
--scroll-area-overflow-x-startThe distance from the horizontal start edge in pixels. On Viewport.
--scroll-area-overflow-x-endThe distance from the horizontal end edge in pixels. On Viewport.
--scroll-area-overflow-y-startThe distance from the vertical start edge in pixels. On Viewport.
--scroll-area-overflow-y-endThe distance from the vertical end edge in pixels. On Viewport.
[data-orientation]Indicates the orientation of the scrollbar. On Scrollbar, Thumb.
[data-hovering]Present when the pointer is over the scroll area. On Scrollbar.
--scroll-area-thumb-heightThe scroll area thumb's height. On Scrollbar.
--scroll-area-thumb-widthThe scroll area thumb's width. On Scrollbar.

Keyboard

ScrollArea adds no keys: Viewport takes focus when its content overflows, and the browser scrolls it with the arrow keys, PageUp, PageDown, Home and End.

Set for you

tabindex="0" while the content overflowskeyboard users can focus the region and scroll itViewport
keeps its own rolethe scrollable region is not hidden from assistive technologyViewport
aria-hidden="true"the custom bars are not read; the native scroll position isScrollbar
aria-hidden="true"the corner piece is not readCorner
role="presentation"the wrapper adds nothing to what is readRoot
role="presentation"the inner wrapper adds nothing to what is readContent

API reference#

3 props across 6 parts, in React syntax, and className, style, render once for every part. Open a row to try it.

Filter props

ScrollArea · all parts

Shared propsEvery part that renders an element takes these.

classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)

styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)

renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Use it in React#

What differs from the React API. Switch the framework at the top of the page.

@▢▢▢▢/react is the React 19 package. Its parts, props, data attributes and error messages are upstream Base UI's, and upstream's own tests run against it.

Parts
Each component is its own entry point and exports one namespace named after it.
```
import { Switch } from '@base-ui-next/react/switch'

export function Example() {
  return (
    <Switch.Root>
      <Switch.Thumb />
    </Switch.Root>
  )
}
```
A part renders the element its API reference names, such as a <span> for Switch.Root.
Props and events
Props and callbacks have upstream's names and signatures: onCheckedChange(checked, details), onOpenChange(open, details), onValueChange(value, details). details carries reason, event, cancel() and allowPropagation(). Native handlers are React's (onClick, onKeyDown), and event.preventBaseUIHandler() stops a part's own handler.
Styling
className takes a string or a function (state) => string; style takes an object or a function (state) => object. The state's data-* attributes are on the element for CSS.
render
render takes an element (render={<a href="/docs" />}) or a function (props, state) => element that spreads props on what it returns.
Refs
ref reaches the part's element. Imperative handles are ref props, as upstream: inputRef, and actionsRef ({ validate } on Field and Form, { unmount, close } on Dialog).
Binding
A part is controlled when its value prop (checked, open, value) is set, and uncontrolled with the default form (defaultChecked, defaultOpen, defaultValue). React has no two-way binding: pair the value with its change callback.
From @base-ui/react
Change the import from @base-ui/react/<component> to @▢▢▢▢/react/<component>.
From @base-ui/react
Nothing else changes: props, parts, data attributes and errors are the same.