Skip to content

shadcn.io is an independent project built on shadcn/ui

Components

Free

Scroll Area for Radix UI

A box of fixed height that scrolls its own content, for a tag list, a chat log or a strip of photos, with a thin scrollbar. For React on Radix UI.

On this page9 sections

A scroll area is a box with a set height or width that scrolls its own content, so a long list stays inside a sidebar, a popover or a card instead of stretching the page. It suits a tag list, a chat log or a row of thumbnails.

When the items should snap one at a time and come with previous and next buttons, use a Carousel.

Preview width

Installation

Sign in to get your install command
Free with an account. It carries your token, so the CLI installs everything in one go.

Anatomy

Scroll Area anatomy: root, viewport, content, scrollbar, thumb

Usage

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

The height on ScrollArea is what makes it scroll. Its content can be any length.

const tags = Array.from({ length: 50 }, (_, i) => `v1.2.0-beta.${50 - i}`);

const Tags = () => (
  <ScrollArea className="h-72 w-48 rounded-md border">
    <div className="p-4">
      <h4 className="mb-4 font-medium text-sm leading-none">Tags</h4>
      {tags.map((tag) => (
        <div className="border-b py-2 text-sm last:border-0" key={tag}>
          {tag}
        </div>
      ))}
    </div>
  </ScrollArea>
);

Accessibility

Radix UI hides the browser's scrollbar and draws its own, which takes no focus. The scrolling box gets no tabIndex from it, so whether Tab can reach a list with nothing focusable inside is left to the browser. When people must be able to scroll it from the keyboard, add tabIndex={0} and an aria-label to ScrollAreaPrimitive.Viewport in components/ui/scroll-area, which already draws a focus ring.

Tab
Moves focus to the scrolling box when it is in the tab order, then on to the links and buttons inside it.
Arrow Down
When the box has focus, scrolls it down a short step.
Arrow Up
When the box has focus, scrolls it up a short step.
Arrow Right
When the box has focus and its content is wider than it, scrolls right.
Arrow Left
When the box has focus and its content is wider than it, scrolls left.
Page Down
When the box has focus, scrolls down by about the height of the box.
Page Up
When the box has focus, scrolls up by about the height of the box.
Home
When the box has focus, scrolls to the top.
End
When the box has focus, scrolls to the bottom.

Demos

Horizontal

Three photos with their photographers' names sit in one row that doesn't wrap, w-max inside a box at most max-w-sm wide, so the extra width becomes the scroll range. This Scroll Area draws only a vertical bar by itself, so the demo adds a ScrollBar with orientation set to horizontal. Use it for a strip of thumbnails or logos that must stay one row tall.

Preview width

RTL

The tag list again, with an Arabic heading and dir set to rtl on the area, so the heading and rows align right and the scrollbar sits on the left edge. Radix UI places its bar from that prop or from a Direction provider, not from the page's own dir. Use it for an Arabic or Hebrew interface.

Preview width

FAQ

Why won't my Scroll Area scroll?

A Scroll Area scrolls only when its own box is shorter than its content, so it needs a height that doesn't come from the content: a class such as h-72, as the demo has, or h-full inside a parent whose height is set.

In a flex column, where the area takes its height from flex-1, add min-h-0 as well. A flex item won't shrink below its content without it, so the area grows to fit everything and has nothing left to scroll.

How do I give a Scroll Area a max height instead of a fixed one?

Put the class on ScrollArea, such as max-h-72. The area then stays as short as its content and starts to scroll once it reaches the limit, which suits a dropdown of results or a comment thread whose length you don't know in advance.

The area is a flex column, and the viewport inside it, the box that actually scrolls, may shrink below its content, so it stops at the area's limit instead of growing past it.

How do I make a Scroll Area scroll horizontally?

Make the content wider than the area and keep it from wrapping: a row with w-max, and whitespace-nowrap on the area, as the Horizontal demo does.

This Scroll Area draws only a vertical bar, so also render ScrollBar with orientation set to horizontal inside it. Radix UI turns sideways scrolling on only while that bar is mounted, so without it the row is cut off and can't be scrolled at all.

How do I keep the Scroll Area scrollbar always visible?

Set type to always on ScrollArea. The default, hover, shows the bar while the pointer is over the area and hides it 600ms after the pointer leaves, a delay you can change with scrollHideDelay. The other two values are scroll, which shows it only while the content moves, and auto, which shows it whenever the content overflows.

How do I change the color of the Scroll Area scrollbar?

Edit ScrollBar in components/ui/scroll-area, which is your code once installed. The thumb is the element whose data-slot is scroll-area-thumb, and its color is the bg-border class, so swap that for the color you want, such as bg-muted-foreground/40. The track behind it stays transparent unless you give ScrollBar a background.

How do I scroll a Scroll Area to the bottom when a new message arrives?

A ref on ScrollArea reaches the outer element, not the box that scrolls. Put an empty div after the last message instead, keep a ref to it, and in a useEffect that depends on the messages call its scrollIntoView with block: "nearest", which scrolls the area to the end.

Scroll only when the reader was already at the end, so someone who moved up to an older message isn't pulled back down. A chat log, a build output and an activity feed all want that exception.

Should I use a Scroll Area or plain CSS overflow?

Use Scroll Area when the bar should look the same in every browser: it hides the native scrollbar and draws a thin themed one that sits over the content instead of taking width from it. Plain overflow-y-auto is enough when the platform's own bar is fine, and it runs no JavaScript, while this component measures the content to size and place its thumb.

Neither one touches the page's own scrollbar. A Scroll Area styles the bar of its own box, and the window keeps the browser's.

Does a Scroll Area work in a right-to-left layout?

Yes, once Radix UI knows the direction. Pass dir set to rtl to ScrollArea, as the RTL demo does, or wrap the app in a Direction provider. Without either, Radix UI writes dir="ltr" on the area's root, so its content reads left to right even on a right-to-left page, and the bar stays on the right.

API Reference

ScrollArea

<div> data-slot="scroll-area"

PropType
dir?Direction

The reading direction. Inherits the nearest DirectionProvider when unset.

scrollHideDelay?number

How long the scrollbars stay after scrolling stops, in milliseconds.

type?ScrollAreaType

When the scrollbars show: auto when it overflows, always, scroll while scrolling, or hover.

asChild?boolean

Merge props onto the child element instead of rendering a host.

className?string

Merged with the part's classes.

AttributeType
data-overflow-x?string

Present when scrollbarXHidden is false.

data-overflow-y?string

Present when scrollbarYHidden is false.

CSS variableType
--corner-heightstring
--corner-widthstring
--thumb-heightstring
--thumb-widthstring

ScrollAreaViewport

<div> data-slot="scroll-area-viewport"

PropType
disableImplicitContentElement?boolean

Disables implicit rendering of an additional wrapper element that measures the content size. When true, a child <ScrollArea.Content> must be rendered as a direct child of the viewport. Implicit rendering of the content element will be removed in the next major release.

nonce?string

A nonce for the styles it injects, for a strict Content Security Policy.

AttributeType
data-at-bottom?string

Present when bottom is true.

data-at-left?string

Present when left is true.

data-at-right?string

Present when right is true.

data-at-top?string

Present when top is true.

data-overflow-x?string

Present when scrollbarXHidden is false.

data-overflow-y?string

Present when scrollbarYHidden is false.

data-ownedbystring

Id of the root part.

ScrollAreaCorner

<div>

AttributeType
data-hover?string

Present when hovering is true.

data-overflow-x?string

Present when scrollbarXHidden is false.

data-overflow-y?string

Present when scrollbarYHidden is false.

data-ownedbystring

Id of the root part.

data-state"hidden" | "visible"

"hidden" or "visible".

Type
"hidden" | "visible"

ScrollBar

data-slot="scroll-area-scrollbar"

PropType
asChild?boolean

Merge props onto the child element instead of rendering a host.

className?string

Merged with the part's classes.

AttributeType
data-orientation?string

Mirrors orientation.