ScrollArea

scroll-area

Adds slim custom scrollbars for vertical, horizontal, or two-axis overflow.

Usage

Vertical scroll

Default orientation=vertical, a thin scroll bar is displayed when the content exceeds the height of the container.

Update log

No. 1 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 2 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 3 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 4 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 5 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 6 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 7 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 8 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 9 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 10 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 11 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

No. 12 Article: Hulian's abstract aggregation component library absorbs the best implementations from various React libraries and unifies them into a set of API and light and dark token.

tsx

<ScrollArea className="h-48 w-72 border border-border p-4">
  {/* Content that exceeds the height of the container */}
</ScrollArea>

Horizontal scrolling

orientation=horizontal, with a row of flex cards for horizontal browsing.

Card 1

Card 2

Card 3

Card 4

Card 5

Card 6

Card 7

Card 8

Card 9

Card 10

Card 11

Card 12

tsx

<ScrollArea orientation="horizontal" className="w-72 border border-border p-4">
  <div className="flex gap-3">{/* Cards */}</div>
</ScrollArea>

Capped scrolling

Use max-h-* for grow-then-scroll: short content shows no scrollbar and leaves none of the empty space below that a fixed height would.

Short content shows no scrollbar, and the container is only as tall as it needs to be.

A fixed height would leave empty space below.

No. 1 : scrolls here once past the cap, and hugs the content below it.

No. 2 : scrolls here once past the cap, and hugs the content below it.

No. 3 : scrolls here once past the cap, and hugs the content below it.

No. 4 : scrolls here once past the cap, and hugs the content below it.

No. 5 : scrolls here once past the cap, and hugs the content below it.

No. 6 : scrolls here once past the cap, and hugs the content below it.

No. 7 : scrolls here once past the cap, and hugs the content below it.

No. 8 : scrolls here once past the cap, and hugs the content below it.

No. 9 : scrolls here once past the cap, and hugs the content below it.

No. 10 : scrolls here once past the cap, and hugs the content below it.

No. 11 : scrolls here once past the cap, and hugs the content below it.

No. 12 : scrolls here once past the cap, and hugs the content below it.

tsx

<ScrollArea className="max-h-40 w-56 border border-border p-4">
  {/* Scrolls only past 40; below that the container is as tall as its content */}
</ScrollArea>

Bi-directional scrolling

orientation=both, horizontal and vertical scroll bars appear at the same time and corner is added in the lower right corner.

No. 1 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 2 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 3 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 4 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 5 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 6 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 7 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 8 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 9 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 10 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 11 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

No. 12 Line: This is a long text that does not wrap into new lines. It is used to simultaneously support the horizontal and vertical scroll bars and the lower right corner.

tsx

<ScrollArea orientation="both" className="h-48 w-72 border border-border p-4">
  {/* wide and tall content */}
</ScrollArea>

When to use

Use ScrollArea for constrained content that needs thin, consistent cross-platform scrollbars. It controls scrollbar styling and orientation only. Use Resizable when users should change the area's size, or Viewport for container-query layout changes.

Import

import { ScrollArea } from "@hulianui/ui"

Props

Name	Type	Default	Description
orientation	`"vertical" \| "horizontal" \| "both"`	`"vertical"`	Scroll direction. `both` renders horizontal and vertical bars plus their corner.
className	`string`	-	Consumer-supplied size constraint on Root, such as `h-48` or `w-64`; without one, content expands instead of scrolling.
viewportClassName	`string`	-	Appended to the inner viewport, which is the element that actually scrolls. `className` lands on Root and cannot reach the viewport, yet clipping happens there, so pass something like `px-1.5` when a flush-mounted control loses its focus ring (#340; see the usage note below).

Slots

Slot	Type	Description
children	`ReactNode`	Scroll content.

Example

tsx

// Vertical scrolling requires a height constraint
<ScrollArea className="h-48 w-72 border border-border bg-surface p-4">
  {/* Long content */}
</ScrollArea>

tsx

// Horizontal scrolling
<ScrollArea orientation="horizontal" className="w-72">
  <div className="flex gap-3">{/* Horizontal cards */}</div>
</ScrollArea>

Usage guidelines

Scrolling requires a size constraint. ScrollArea has no intrinsic size, so constrain it through className or content will expand the container and no scrollbar will appear. Use h-* for a fixed panel, which leaves empty space below short content, and max-h-* for grow-then-scroll, which stays snug until the cap is reached (w-* / max-w-* horizontally). Before 0.61.0 max-h-* silently clipped the overflow, with no scrollbar, no wheel response and no keyboard access; both forms now work (#342).
The scrollbar is an overlay, so the content must reserve its own gutter. The bar is absolutely positioned, takes no layout width, and is w-2 (8px) wide; a horizontal bar is the same height. Give the content at least `pr-2.5` (10px: an 8px bar plus 2px of breathing room), or pb-2.5 when scrolling horizontally. A smaller gutter such as the common pr-1 (4px) leaves the bar sitting on top of the rightmost column (#118). This is an explicit convention rather than component behaviour, because only the consumer knows whether the gutter belongs on the content wrapper or on individual columns.
A flush-mounted control loses its focus ring; reserve room with `viewportClassName` (#340). The clipping described below does not only affect content: a w-full Input sits flush against the viewport, so the 4px that ring-2 + ring-offset-2 paints outside the box falls beyond the viewport and is cut away. The visible result is a focus ring reduced to its top and bottom edges (spare height keeps those two alive). Padding on Root does not help, because the viewport is what clips. Pass viewportClassName="px-1.5". The component ships no default gutter, because only you know whether the room belongs on the scroll container or on individual columns.

Overflow on the undeclared axis is locked (hidden), never silently scrollable. A vertical viewport gets overflow-x: hidden, a horizontal viewport gets overflow-y: hidden (both leaves both axes open). Base UI styles the viewport with two-axis overflow: scroll and hides the native bars, so content even 1px wider than the viewport used to pan sideways under a trackpad swipe with no scrollbar to explain it, and it looked like a broken layout (#287). Content inside a vertical area therefore has to fit its width (w-full / min-w-0 / internal truncation); anything wider is clipped rather than scrollable. Declare orientation="both" when you really want two-axis scrolling.

Layout · AdminLayout · Viewport · Resizable · AspectRatio · FitScreen

Playground

orientation