Skip to content
WunderUI

Scroll Area

Pro

A bounded region that scrolls with a scrollbar that looks the same on every platform. Wheel, touch and keyboard scroll it like a native region.

Playground

Installation

Scroll Area comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import { ScrollArea, ScrollBar } from "@wunderui/react"

Then use it:

tsx
import { ScrollArea } from "@/components/ui/scroll-area"

const notes = Array.from({ length: 20 }, (_, index) => `Release note ${index + 1}`)

export function ReleaseNotes() {
  return (
    <ScrollArea role="group" aria-label="Release notes" className="h-48 w-72 rounded-xl border border-border bg-card">
      <ul className="flex flex-col gap-2 p-4 text-sm">
        {notes.map((note) => (
          <li key={note}>{note}</li>
        ))}
      </ul>
    </ScrollArea>
  )
}

Expected result: You see a 192 px high box with the first release notes and a slim scrollbar at the right edge. Wheel, keyboard and dragging the bar scroll the list.

When to use

Use Scroll Area for

  • A panel with its own scrolling inside a fixed layout: an activity list, a log, a side panel
  • A scrollbar that looks the same on every platform
  • A wide table or a row of tiles that scrolls inside its own window

Use something else for

  • Plain overflow for ordinary content that scrolls with the page: plain overflow is enough
  • Carousel for items that are paged one by one, with buttons
  • Table for tabular data that needs sorting, selection and a sticky header

Overflow

A scroll area scrolls where its content is bigger than its box. The vertical bar comes with it, for sideways scrolling add a horizontal ScrollBar, and with nothing to scroll no bar is drawn.

Scrollbar

The bar is always visible by default and lies over the content without taking room. To show it only on hover or while scrolling, hide it with the data attributes it carries.

Keyboard interactions

While the content overflows, the viewport is in the tab order and shows a focus ring, so the keyboard scrolls it like a native region. With nothing to scroll it is not focusable.

TaborShiftTab
Moves focus into the region and on to the next control.
ArrowDownorArrowUp
Scrolls vertically by a line, 40 px in Chrome.
ArrowRightorArrowLeft
Scrolls sideways by the same step, where the content is wider than the box.
PageDownorPageUporSpace
Scrolls by almost a page. Space scrolls down.
HomeorEnd
Scrolls to the top or the bottom.

Step sizes come from the browser. In Chrome an arrow key scrolls 40 px.

Behavior and motion

What the region does with its content, the bars and the keyboard.

Overflow and bars
A bar appears only on an axis that overflows. The root brings the vertical one, you add a horizontal one as a child, and a corner fills the gap where both show.
Overlay bars
The bars are 10 px wide and float over the content, so keep 16 px of padding on that side. Wide content without a horizontal bar still scrolls, just with no sign of it.
Native scrolling
The viewport is a real scroll container with the native scrollbar hidden. Wheel, trackpad, touch, keyboard and dragging the thumb all work, and scrolling to the end does not move the page behind.
Focus
An overflowing viewport takes focus with Tab and shows a 2 px indigo-light outline. The root border stays grey unless you add the focus-visible border rule, as the examples do.
Role and name
The viewport has no name of its own. Give the root a group role and an aria-label so screen readers say what scrolls, or a region role if the area is a landmark.
Scrollbar visibility
The bar is always visible by default, and data attributes expose hovering, scrolling and overflow so you can show it only on those. Keep it visible where it is the only sign of more content.
Thumb colour
The thumb is the foreground colour at 45 % (60 % on hover), about 3 to 1 against a card in both themes. To restyle it, target the thumb from a class on the root, like the Scrollbar card does.
Motion
There is no animation of its own, since scrolling is the browser's. The hover-only bar fades with opacity, and a fade stays under reduced motion.

Anatomy

The parts of a scroll area, numbered in the figure. A horizontal bar is added as a child, the rest comes with the root.

  • data-slot="scroll-area"

    The root: a positioned box that you give a size, a border and a radius. It brings the viewport, the content wrapper, a vertical scrollbar and the corner.

  • data-slot="scroll-area-viewport"

    The element that scrolls. It fills the root, follows its radius, stops scroll chaining and shows a focus ring, but takes focus only while the content overflows.

  • data-slot="scroll-area-content"

    The wrapper around your children. It grows with them and is measured to size the thumb.

  • data-slot="scroll-area-scrollbar"Optional

    The track of a bar, drawn only on an axis that overflows. The root renders the vertical one, you add a horizontal one as a child, and it floats over the content.

  • data-slot="scroll-area-thumb"

    The draggable handle in the track, whose length shows how much of the content is visible. It has about 3 to 1 contrast against a card in light and dark, and darkens under the pointer.

  • Optional

    Fills the square where a vertical and a horizontal bar meet, so the two tracks do not overlap.

Best practices

  • Do

    Give the root a height, or a width for sideways scrolling. The viewport fills the root, so without a bounded size the content just grows and nothing scrolls.

  • Do

    Put the border, radius and background on the root. The viewport inherits the radius, so content is clipped at the rounded corners.

  • Do

    Give the root a group role and an aria-label so screen readers announce what scrolls. Add a focus-visible border rule on the root for the indigo focus border.

  • Do

    Add a horizontal ScrollBar whenever the content can be wider than the box, so readers can see it scrolls sideways.

  • Don’t

    Don't nest scroll areas. Two scrolling regions fight over the wheel and the keyboard, so reduce the inner one to a plain list.

  • Don’t

    Don't hide the bar where it is the only sign that there is more. Keep it always visible there.

  • Don’t

    Don't wrap the whole page. The browser's own page scrolling is faster and keeps find-in-page, the back button and the address bar behaviour.

API reference

Scroll Area wraps the Base UI scroll area and passes its props on. The vertical ScrollBar comes with the root, a horizontal one is added as a child, and the thumb and corner belong to the root.

The root: a positioned box that you give a size, a border and a radius. It brings the viewport, the content wrapper, a vertical scrollbar and the corner.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Classes for the root. Give it a size, a border, a radius and a background.
overflowEdgeThresholdnumber | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>0The threshold in pixels that must be passed before the overflow edge attributes are applied. Accepts a single number for all edges or an object to configure them individually.

The track of a bar, drawn only on an axis that overflows. The root renders the vertical one, you add a horizontal one as a child, and it floats over the content.

PropTypeDefaultDescription
orientation"vertical" | "horizontal""vertical"Whether the scrollbar controls vertical or horizontal scroll.
keepMountedbooleanfalseWhether to keep the HTML element in the DOM when the viewport isn't scrollable.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("scroll-area")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.