Scroll Area
Create accessible, theme-aware scrollable regions with native browser scrolling.
Scroll Area provides a constrained viewport for overflowing content. It keeps browser-native scrolling and keyboard behavior while applying Puzzle's scrollbar styling.
Import
import { ScrollArea } from "@puzzle-ui/ui";Basic usage
Give the component a height or max-height so vertical overflow can occur. The component fills its available width by default.
Scroll direction
Use the orientation prop to choose which axis can scroll.
vertical(default): vertical scrolling only.horizontal: horizontal scrolling only.both: scrolling on both axes.
Keyboard and accessibility
The viewport is focusable by default, so users can scroll it with the keyboard using the browser's native scrolling keys (for example, Arrow keys, Page Up, Page Down, Home, and End).
- Provide an accessible name with
aria-labeloraria-labelledbywhen the scrollable region is meaningful as a named region. - When an accessible name is provided and no explicit role is set, the component uses
role="region". - Use
tabIndex={-1}to remove the viewport from sequential keyboard navigation while keeping it programmatically focusable. - Touch, trackpad, wheel, and pointer scrolling remain native.
API
Props
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical" | "horizontal" | "both" | "vertical" | Which scroll axes are enabled. |
children | ReactNode | - | Scrollable content. |
className | string | - | Additional CSS classes. |
tabIndex | number | 0 | Keyboard focus order for the viewport. |
role | string | "region" when named | Explicit semantic role. |
All standard HTML div attributes are supported, including id, title, style, data-*, aria-*, event handlers, and ref.
Caller-provided styles can override the orientation's default overflow styles.
Layout
A Scroll Area needs a constrained dimension to overflow:
- For vertical scrolling, set
heightormaxHeight. - For horizontal scrolling, constrain the width and make the inner content wider than the viewport.
- For both axes, constrain both dimensions as needed.
Theming
The scrollbar thumb uses --puzzle-color-border and follows the active light, dark, or scoped theme.
Scrollbar rendering and visibility remain subject to the browser and operating-system settings.