# Scroll Area

A scrollable container with custom, always-styled scrollbars.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/scroll-area
- Tier: Core and Pro

## Install

Scroll Area ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

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

- Plain overflow for ordinary content that scrolls with the page: plain overflow is enough
- [Carousel](https://wunderui.com/components/carousel) for items that are paged one by one, with buttons
- [Table](https://wunderui.com/components/table) for tabular data that needs sorting, selection and a sticky header

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the region and on to the next control. |
| `ArrowDown` or `ArrowUp` | Scrolls vertically by a line, 40 px in Chrome. |
| `ArrowRight` or `ArrowLeft` | Scrolls sideways by the same step, where the content is wider than the box. |
| `PageDown` or `PageUp` or `Space` | Scrolls by almost a page. Space scrolls down. |
| `Home` or `End` | Scrolls to the top or the bottom. |

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

## Behavior

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

- `ScrollArea`: 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.
- `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.
- `Content`: The wrapper around your children. It grows with them and is measured to size the thumb.
- `ScrollBar`: 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.
- `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.
- `Corner`: 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.
- Put the border, radius and background on the root. The viewport inherits the radius, so content is clipped at the rounded corners.
- 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.
- 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 hide the bar where it is the only sign that there is more. Keep it always visible there.
- 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

### ScrollArea

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Classes for the root. Give it a size, a border, a radius and a background. |
| overflowEdgeThreshold | number \| Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }> | 0 | The 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. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

### ScrollBar

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| keepMounted | boolean | false | Whether to keep the HTML element in the DOM when the viewport isn't scrollable. |
| orientation | 'vertical' \| 'horizontal' | "vertical" | Whether the scrollbar controls vertical or horizontal scroll. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Overflow: vertical, horizontal, both, or none

### Scrollbar: always visible, or on hover and while scrolling

## In context

### Activity panel with a fixed header

The panel keeps its header in place and only the list scrolls. Focus the list and use the arrow keys, Page Down or End; its name comes from the group label.

### Wide table that scrolls in both directions

The table is wider and taller than its window, so both bars show and meet in the corner. The page itself does not scroll sideways.

### A rail of recent projects

A row of tiles that scrolls sideways with a horizontal bar. Arrow Left and Arrow Right scroll it when the region has focus.

## For AI agents

`get_component("scroll-area")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
