Scroll Area
A headless scroll area primitive that keeps native browser scrolling while exposing composable parts.
Features
- Native browser scrolling
- Composable scrollbar anatomy
- Vertical and horizontal orientation hooks
- Visibility state data attributes
- Token-friendly unstyled parts
Installation
npm install @ariaui/scroll-area
Examples
This example matches the shadcn-style Figma reference: a compact tag list inside a native scroll viewport, with a force-mounted custom scrollbar part for styling.
Default
Scrollable release tags using native viewport scrolling.
No preview output yet.
Horizontal
Horizontally scrollable status cards using native viewport scrolling.
No preview output yet.
Select Menu
A select menu styled scroll area with native viewport scrolling.
No preview output yet.
Framer Motion
A Framer Motion scroll area with an animated viewport and progress bar.
No preview output yet.
Anatomy
import * as ScrollArea from "@ariaui/scroll-area";
export default function Example() {
return (
<ScrollArea.Root>
<ScrollArea.Viewport />
</ScrollArea.Root>
);
}
API Reference
Root
Relative overflow shell that provides scroll area configuration to descendant parts.
| Prop | Type | Default |
|---|---|---|
type | "auto" | "always" | "scroll" | "hover" | "never" | "hover" |
Viewport
Native scroll container. Style width, height, padding, and scrollbar visibility from your app.
| Prop | Type | Default |
|---|---|---|
asChild | boolean | false |
maxVisibleItems | number | - |
anchorSelected | boolean | false |
| Attribute | Values |
|---|---|
| data-ariaui-scroll-area-viewport | "true" |
Scrollbar
Render-only compatibility rail. Native browser scrollbars provide the actual scrolling surface.
| Prop | Type | Default |
|---|---|---|
orientation | "vertical" | "horizontal" | "vertical" |
| Attribute | Values |
|---|---|
| data-orientation | "vertical" | "horizontal" |
| data-state | "visible" |
Thumb
Render-only compatibility thumb rendered inside Scrollbar.
| Attribute | Values |
|---|---|
| data-state | "visible" |
Accessibility
Scroll Area keeps browser-native scrolling behavior:
- Use
Viewportas the actual scroll container and give it a visible label witharia-labelwhen the scrollable region needs to be announced independently. - If you render compatibility scrollbar parts, avoid adding roles to them; the native scroll container remains the accessible control.
- Add
tabIndex={0}toViewportonly when keyboard users need to focus and scroll a nested region directly. - Keep content semantics inside
Viewport; the primitive does not change headings, lists, or landmark roles.