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
scroll-area · base base · style base-lyraOpen under the product themeA 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.
scroll-area-a-long-list · base base · style base-lyraOpen under the product themeimport { 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.
scroll-area-in-a-card · base base · style base-lyraOpen under the product themeimport { 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
cardinstead.
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.
| Key | Action | Notes |
|---|---|---|
| Tab | Moves focus onto the viewport when it is scrollable | One tab stop for the region. Base UI drops it when there is nothing to scroll. |
| Shift+Tab | Moves focus back out of the viewport | A single stop in reverse too, so focus does not step through the rails. |
| Arrow keys | Scroll the focused viewport | The browser's own behaviour on a focused scroll container, along the allowed axes. |
| Page Up, Page Down | Scroll the focused viewport by a page | The browser's default, not a key this component binds. |
| Home, End | Scroll to the start or end of the focused viewport | Again the browser's default on a scroll container. |
Contrast: 36 measured token pairs, 15 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below 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
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every inner part, always | scroll-area, scroll-area-viewport, scroll-area-scrollbar, scroll-area-thumb, scroll-area-corner |
| data-orientation | On a scrollbar, set by Base UI | vertical or horizontal |
| data-hovering, data-scrolling | On a scrollbar while hovered or while the region scrolls | What the rail's fade-in is keyed to |