Skip to content

Scroll area

Scrolls content in a frame with scrollbars that match the theme.

Activity

9 updates
scroll-area-demo.tsx

Installation

The CLI adds the files, packages, theme variables, and Tailwind plugin that this component uses. Before you run it, set up your project.

Usage

activity.tsx

Composition

  • ScrollAreaRoot

    Owns the scrollbars. Set its height, then compose the parts. ScrollArea does this for you.

    • ScrollAreaViewport
      • ScrollAreaContent
    • ScrollAreaScrollbarOptionalRepeats
      • ScrollAreaThumb
    • ScrollAreaCornerOptional

ScrollAreaContext Renders a function with the full scroll-area api: position, overflow, progress, scrollbar state, and scroll methods. useScrollArea returns the same api.

Horizontal

Set orientation to "horizontal" to scroll one row sideways.

scroll-area-horizontal-demo.tsx

Both axes

Set orientation to "both" to show a scrollbar for each axis.

Team coverage

Week of Nov 18

scroll-area-both-demo.tsx

Scroll from a control

Call useScrollArea in a child to read the position and scroll. Also install Button.

scroll-area-to-top-demo.tsx

Composition

Compose the parts to place your own controls. ScrollAreaContext reads the progress. Also install Button.

scroll-area-context-demo.tsx

API reference

ScrollArea

orientation: "vertical" | "horizontal" | "both" = "vertical"
Sets which axes scroll. Content on the other axis is clipped.
dir: "ltr" | "rtl"
Sets the scroll direction. By default, the direction comes from the page.
aria-label: string
Names the scroll region for screen readers. Add it when there is no visible heading.
tabIndex: number
Overrides the tab stop. By default, the viewport takes focus only while content overflows.
className: string
Sets the height and the frame around the content. A fixed height makes the area scroll.
ids: ElementIds
Sets the ids of the root, viewport, content, scrollbar, and thumb.

ScrollAreaRoot

Owns the machine and the frame. Compose the viewport, the content, and the scrollbars inside it.

orientation: "vertical" | "horizontal" | "both" = "vertical"
Sets the axes that scroll. The scrollbar parts also read it from context.

ScrollAreaViewport

The scrolling element. It hides the native scrollbar and takes focus while content overflows.

aria-label: string
Names the scroll region when it has no heading.

ScrollAreaContent

Holds the content that scrolls inside the viewport.

ScrollAreaScrollbar

Draws one machine scrollbar. Without children it draws a matching thumb.

orientation: "vertical" | "horizontal" = "vertical"
Sets the axis of the scrollbar.

ScrollAreaThumb

Draws the draggable thumb. Put it inside a ScrollAreaScrollbar of the same orientation.

orientation: "vertical" | "horizontal" = "vertical"
Sets the axis of the thumb.

ScrollAreaCorner

Fills the corner where both scrollbars meet. Render it when both axes scroll.

ScrollAreaContext

Renders no DOM. Its children receive the full scroll-area api: isAtTop, isAtBottom, isAtLeft, isAtRight, hasOverflowX, hasOverflowY, getScrollProgress, getScrollbarState, scrollTo, and scrollToEdge.

children: (api: ScrollAreaApi) => ReactNodeRequired
Draws custom content inside ScrollArea.