Scroll Area

Visual Hierarchy

Scroll areas should have clear boundaries using border border-border and rounded-md to signal containment. The scrollbar thumb uses bg-border for subtlety, becoming more visible on hover. Use type="always" when discoverability of hidden content is critical.

Spacing & Layout

Always set explicit dimensions on the ScrollArea container ( h-72, h-[200px]). Apply padding to the inner content wrapper rather than the ScrollArea itself to avoid clipping scrollbar tracks. Use p-4 on the child container for consistent content insets.

Responsive Behavior

On mobile, the scrollbar is narrower (2.5 units wide) for minimal visual footprint. Consider using percentage-based or viewport-relative heights ( h-[50vh]) for responsive scroll containers. Horizontal scroll areas should use whitespace-nowrap with touch-friendly scrollbar sizing.

Color & Contrast

The scrollbar thumb uses the bg-border semantic token, which adapts to light and dark mode automatically. Scrollbar tracks use transparent borders ( border-l-transparent) for clean alignment. The custom scrollbar provides consistent styling across browsers while maintaining sufficient contrast for visibility.

Keyboard Navigation

• Tab -- Move focus into the scroll area viewport
• Arrow Up / Arrow Down -- Scroll vertically when the viewport is focused
• Arrow Left / Arrow Right -- Scroll horizontally when a horizontal scrollbar is present
• Page Up / Page Down -- Scroll by one viewport height
• Home / End -- Jump to the start or end of the scrollable content

Screen Reader Support

• The viewport is focusable and announces its scrollable nature to assistive technology
• Custom scrollbars are purely decorative -- screen readers use native scroll semantics
• Use aria-label on the ScrollArea to describe its content region
• For live-updating content (e.g., chat logs), add aria-live="polite" or role="log"

Focus Management

The viewport uses focus-visible:ring-[3px] with ring-ring/50 for a visible focus indicator. Focus is applied to the viewport element, not the outer container, so keyboard users can immediately scroll. The focus ring inherits the container's border radius via rounded-[inherit].

RTL Support

Set dir="rtl" on the ScrollArea to enable right-to-left scroll behavior. Horizontal scrollbars will reverse direction to match the reading order. Content within the scroll area should also be set to RTL for consistent layout.

ARIA Attributes

{/* Standard scrollable region with accessible label */}
<ScrollArea className="h-72 w-48 rounded-md border" aria-label="Version tags">
  {/* Content */}
</ScrollArea>

{/* Scroll area within a labeled section */}
<section aria-labelledby="notifications-heading">
  <h2 id="notifications-heading">Notifications</h2>
  <ScrollArea className="h-[300px]">
    {/* Notification list */}
  </ScrollArea>
</section>

{/* Scroll area with role and description */}
<ScrollArea
  className="h-[200px]"
  role="log"
  aria-label="Activity log"
  aria-live="polite"
>
  {/* Live-updating log content */}
</ScrollArea>