affectUI › Components › Data display
Scroll Area
A box that scrolls the browser's own way with a slim scrollbar of its own – it shows on hover and while scrolling, a draggable thumb, up and down or sideways, soft fades where there is more.
Free and open source (MIT). Install: npx shadcn@latest add https://www.affectui.com/r/scroll-area.json · Import from @/components/ui/scroll-area
When to use
- A list, log or panel with a fixed height inside a card: sources, steps, messages, a run's output
- A row that is wider than its card – attached files, chips, tabs – scrolled sideways
- Anywhere the browser's thick scrollbar would look out of place, but scrolling should stay exactly as people know it
When not to use
- The page itself – let the window scroll with its own bar
- A long table with sorting and selection – use the Data Table, which brings its own scroller
- Code – the Code Block scrolls its own lines
- Panes the user should size – use Resizable and put a Scroll Area inside each pane
Usage
import { ScrollArea } from "@/components/ui/scroll-area";
export function Sources({ items }: { items: { title: string; site: string }[] }) {
return (
<ScrollArea maxHeight={240} fade aria-label="Sources">
<ul>
{items.map((s) => (
<li key={s.title}>
{s.title} · {s.site}
</li>
))}
</ul>
</ScrollArea>
);
}Props
| Name | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "both" | "vertical" | Which way it scrolls; the other way is clipped |
type | "hover" | "scroll" | "always" | "hover" | When the bar shows: while the pointer is over the box or it scrolls · only while it scrolls · always, as long as there is more |
fade | boolean | false | Soft fades at the edges where there is more to scroll; they shrink as you reach an end |
maxHeight | number | string | How tall it grows before it scrolls. Or give it a fixed height with className or style | |
viewportRef | Ref<HTMLDivElement> | The element that scrolls – for scrollTo, scrollTop or an IntersectionObserver root | |
onScroll | UIEventHandler<HTMLDivElement> | Fires on the element that scrolls | |
aria-label | string | Names the scrolling region for screen readers (or aria-labelledby) | |
...div props | ComponentProps<"div"> | className, style, id, ref … go to the outer box |
Keyboard
- Tab: Reaches the box, but only while it has something to scroll
- ↑ / ↓ / ← / →: Scroll a little – the browser's own keys
- Page Up / Page Down / Space: Scroll a page
- Home / End: Jump to the start or the end
Accessibility
- Scrolling stays the browser's own – wheel, trackpad, touch, keyboard, find-in-page and scroll-into-view all work, nothing is hijacked
- The box becomes a Tab stop only while it overflows, so keyboard users can scroll content that has no controls; when it has a name it is a region
- The drawn bar is hidden from screen readers – it only shows where you are
- The focus ring is drawn inside the box (offset −2px), so a card's edge never cuts it; only on keyboard focus
Responsive
- Follows its box and its content as either changes size – new rows, a narrower window, fonts loading
- Touch screens scroll with the finger as usual; the slim bar only shows where you are while you scroll
- Right to left: the bar sits on the left and the sideways thumb runs from the right
- Dark mode built in: switches when an ancestor (usually <html>) has the class dark or data-theme="dark"
Requirements
- React 19
Related
- Resizable – Panes side by side or stacked with a line between them you can drag – sizes in percent, a smallest and largest size, panes that fold away, arrow keys, Home, End and Enter on the handle, a double-click to reset
- Data Table – Spreadsheet-style table: select cells and ranges, edit in place, copy and paste, undo and sort
- Code Block – Code to read and copy – a header with the file name or language and a copy button, line numbers, highlighted lines, long lines that scroll inside and a small built-in colorizer
- Separator – A thin line between groups – across or upright between tools, an optional word in its middle like "or" or "Earlier", decorative or a real separator for screen readers