Skip to content
opsinjs
Edit this page

Components

ScrollArea

A bounded scrolling region with a thin neutral scrollbar that keeps a card or panel's overflow reachable without replacing the page's own native scroll.

Usage

pnpm dlx shadcn@latest add @opsinjs/scroll-area

The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.

import { ScrollArea } from "@/components/ui/scroll-area"
<ScrollArea maxHeight="16rem" className="rounded-lg border">
  <ul>
    {items.map((item) => (
      <li key={item.id}>{item.label}</li>
    ))}
  </ul>
</ScrollArea>

Examples

Theme
Density
Text
Status
Accent theme
Accent
scroll-area · base base · style base-lyraOpen under the product theme

A long list

The list outruns its box, so maxHeight bounds the region and the rail appears while the page around it keeps its native scroll.

Theme
Density
Text
Status
Accent theme
Accent
scroll-area-a-long-list · base base · style base-lyraOpen under the product theme
scroll-area-a-long-list.tsx
import { ScrollArea } from "@/components/ui/scroll-area"

const ITEMS = [
  "Blood pressure cuff",
  "Pill organiser",
  "Reading glasses",
  "Water bottle",
  "Appointment card",
  "Notebook and pen",
  "Phone charger",
  "House keys",
  "Bus pass",
  "Umbrella",
  "Shopping list",
  "Library book",
  "Spare batteries",
  "First aid kit",
  "Torch",
]

export default function ScrollAreaALongList() {
  return (
    <ScrollArea
      maxHeight="12rem"
      className="w-full max-w-xs rounded-opsin-lg border border-border bg-card"
    >
      <ul className="m-0 flex list-none flex-col p-opsin-2">
        {ITEMS.map((item) => (
          <li
            key={item}
            className="rounded-opsin-sm px-opsin-3 py-opsin-2 text-opsin-body [color:var(--foreground)]"
          >
            {item}
          </li>
        ))}
      </ul>
    </ScrollArea>
  )
}

In a card

One bounded panel with a heading fixed above the region, so maxHeight makes only the card body overflow and scroll.

Theme
Density
Text
Status
Accent theme
Accent
scroll-area-in-a-card · base base · style base-lyraOpen under the product theme
scroll-area-in-a-card.tsx
import { ScrollArea } from "@/components/ui/scroll-area"

const PARAGRAPHS = [
  "This panel holds a longer stretch of text than the card can show at once, so the body scrolls while the heading above it stays put.",
  "A scrolling region belongs to one bounded block like this one. The page it sits on keeps the browser's own scroll, so a reader who turns their text size up still reaches every word.",
  "The rail on the right is quiet neutral chrome. It carries no status and no category, and it fades in as the reader scrolls rather than sitting as a fixed line.",
  "When the region is this short, most readers reach its end in a few flicks. The point of bounding it is to keep the card a fixed size on the surface, not to hide the content.",
  "Keyboard readers reach this region as one tab stop and scroll it with the arrow keys, so the content is reachable without a pointer.",
]

export default function ScrollAreaInACard() {
  return (
    <div className="w-full max-w-sm overflow-hidden rounded-opsin-lg border border-border bg-card">
      <div className="border-b border-border px-opsin-4 py-opsin-3 text-opsin-headline [color:var(--foreground)]">
        About this panel
      </div>
      <ScrollArea maxHeight="11rem">
        <div className="flex flex-col gap-opsin-3 px-opsin-4 py-opsin-3 text-opsin-body [color:var(--foreground)]">
          {PARAGRAPHS.map((paragraph) => (
            <p key={paragraph} className="m-0">
              {paragraph}
            </p>
          ))}
        </div>
      </ScrollArea>
    </div>
  )
}

When to use it

Use it when

  • Bounding one card, panel or list to a height where its content is longer than the box.
  • A wide row of cards or a table that scrolls sideways inside its column.
  • Holding one block's height steady on a surface that still scrolls natively.

Do not use it when

  • Wrapping the whole page or the reading column, where a bounded height clips content at 200% text.Use the browser's own page scroll instead.
  • A small block that already fits, wrapped on the chance that it might grow.Use card instead.

Accessibility

The viewport holds a keyboard tab stop and takes an accessible name through label or labelledBy. Reflow and target size pass, with no colour-axis, token, px or colour-literal issue. The audit fixed one serious defect: the viewport was not a reliable tab stop and had no name, so a screen reader met an unnamed stop. The default demo and both examples now name their region, one by pointing labelledBy at its on-screen heading.

Residual items.

  • In the card example the rounded corners can partly clip the focus ring at the flush bottom edge, though the indicator stays perceivable.
  • The thumb's contrast and the pairs below are not measured in source.
KeyActionNotes
TabMoves focus onto the viewport when it is scrollableOne tab stop for the region. Base UI drops it when there is nothing to scroll.
Shift+TabMoves focus back out of the viewportA single stop in reverse too, so focus does not step through the rails.
Arrow keysScroll the focused viewportThe browser's own behaviour on a focused scroll container, along the allowed axes.
Page Up, Page DownScroll the focused viewport by a pageThe browser's default, not a key this component binds.
Home, EndScroll to the start or end of the focused viewportAgain the browser's default on a scroll container.
Contrast: 36 measured token pairs, 15 below floor
PairThemeAPCA LcWCAG 2.2Floor
body text on the pagelight101.617.18:1Pass
body text on the pagedark-100.518.00:1Pass
body text on a cardlight104.717.96:1Pass
body text on a carddark-99.616.32:1Pass
body text on the muted groundlight98.116.32:1Pass
body text on the muted grounddark-97.513.77:1Pass
secondary text on the pagelight83.97.42:1Pass
secondary text on the pagedark-80.713.44:1Pass
secondary text on a cardlight87.07.76:1Pass
secondary text on a carddark-79.812.19:1Pass
secondary text on the muted groundlight80.47.05:1Pass
secondary text on the muted grounddark-77.810.28:1Pass
a hairline boundary on the pagelight19.31.41:1Below floor
a hairline boundary on the pagedark-8.21.90:1Below floor
a hairline boundary on a cardlight22.41.47:1Below floor
a hairline boundary on a carddark-7.31.72:1Below floor
a hairline boundary on the muted groundlight15.81.34:1Below floor
a hairline boundary on the muted grounddark0.01.45:1Below floor
a placeholder boundary on the pagelight69.84.52:1Pass
a placeholder boundary on the pagedark-51.07.62:1Pass
a placeholder boundary on a cardlight72.84.72:1Pass
a placeholder boundary on a carddark-50.16.91:1Pass
a placeholder boundary on the muted groundlight66.24.29:1Pass
a placeholder boundary on the muted grounddark-48.15.83:1Pass
a placeholder fill on the pagelight8.31.18:1Below floor
a placeholder fill on the pagedark-8.21.90:1Below floor
a placeholder fill on a cardlight11.41.23:1Below floor
a placeholder fill on a carddark-7.31.72:1Below floor
a placeholder fill on the muted groundlight0.01.12:1Below floor
a placeholder fill on the muted grounddark0.01.45:1Below floor
a placeholder boundary on its own filllight58.93.84:1Pass
a placeholder boundary on its own filldark-41.54.01:1Below floor
the card hairline on the pagelight69.84.52:1Pass
the card hairline on the pagedark-28.74.19:1Below floor
the card hairline on a cardlight72.84.72:1Pass
the card hairline on a carddark-27.93.80:1Below floor

These are the measured token pairs this component draws colour from, not a measurement of the component itself.

Props interface

Prop

Type

Generated from ScrollAreaProps in registry/bases/base/scroll-area.tsx.

maxHeight gives the region something to overflow, so set it in a rem rather than a pixel count. Given neither it nor a height class, the region grows to fit and a development warning names the omission. className is the one route by which colour reaches the region, and the two-colour-axes rule applies in full.

Data attributes

AttributeConditionValue
data-slotOn the root and every inner part, alwaysscroll-area, scroll-area-viewport, scroll-area-scrollbar, scroll-area-thumb, scroll-area-corner
data-orientationOn a scrollbar, set by Base UIvertical or horizontal
data-hovering, data-scrollingOn a scrollbar while hovered or while the region scrollsWhat the rail's fade-in is keyed to