Scroll Area

The Scroll Area component provides a cross-browser consistent scrolling experience with fully customizable scrollbars. It’s ideal for replacing native scrollbars with custom-styled ones while maintaining accessibility.

Import

import { ScrollArea } from '@base-ui/react/scroll-area';

Basic Usage

<ScrollArea.Root>
  <ScrollArea.Viewport>
    Your scrollable content goes here...
  </ScrollArea.Viewport>
  
  <ScrollArea.Scrollbar orientation="vertical">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  
  <ScrollArea.Scrollbar orientation="horizontal">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  
  <ScrollArea.Corner />
</ScrollArea.Root>

Key Features

Custom Scrollbars: Full control over scrollbar appearance and behavior.
Cross-Browser: Consistent scrolling experience across all browsers.
Overflow Detection: Track scroll position and overflow edges with state attributes.
Touch Support: Optimized for touch devices with proper modality detection.
Accessibility: Keyboard navigation and focus management built-in.
Hover States: Automatically tracks when the scroll area is hovered.
Overflow Edge Threshold: Configure when overflow edge indicators appear.

Components

ScrollArea.Root

The root container for the scroll area. Renders a <div> element. Props:

overflowEdgeThreshold - Threshold in pixels before overflow edge attributes are applied (default: 0). Can be a number or an object with xStart, xEnd, yStart, yEnd properties.

State attributes:

data-scrolling - Present when scrolling is active
data-overflow-x-start - Overflow detected at horizontal start
data-overflow-x-end - Overflow detected at horizontal end
data-overflow-y-start - Overflow detected at vertical start
data-overflow-y-end - Overflow detected at vertical end

ScrollArea.Viewport

The actual scrollable container. Renders a <div> element with overflow: scroll. State attributes: Inherits all state attributes from ScrollArea.Root.

ScrollArea.Scrollbar

A vertical or horizontal scrollbar. Renders a <div> element. Props:

orientation - Direction of scrolling: 'vertical' or 'horizontal' (default: 'vertical')
keepMounted - Keep scrollbar in DOM when not scrollable (default: false)

State attributes:

data-hovering - Present when scroll area is hovered
data-scrolling - Present when scrolling in this orientation
data-orientation - The orientation value (vertical or horizontal)

ScrollArea.Thumb

The draggable part of the scrollbar that indicates scroll position. Renders a <div> element. State attributes:

data-orientation - The orientation value from parent scrollbar

ScrollArea.Corner

The corner element where horizontal and vertical scrollbars meet. Renders a <div> element.

Styling Example

<ScrollArea.Root className="scroll-area">
  <ScrollArea.Viewport className="scroll-viewport">
    <div style={{ height: 1000 }}>
      Tall content that requires scrolling...
    </div>
  </ScrollArea.Viewport>
  
  <ScrollArea.Scrollbar 
    orientation="vertical" 
    className="scroll-scrollbar"
  >
    <ScrollArea.Thumb className="scroll-thumb" />
  </ScrollArea.Scrollbar>
  
  <ScrollArea.Corner className="scroll-corner" />
</ScrollArea.Root>

.scroll-area {
  width: 400px;
  height: 300px;
}

.scroll-viewport {
  width: 100%;
  height: 100%;
}

.scroll-scrollbar {
  background: rgba(0, 0, 0, 0.1);
  border-radius: 8px;
  padding: 2px;
  width: 12px;
}

.scroll-scrollbar[data-hovering] {
  background: rgba(0, 0, 0, 0.15);
}

.scroll-scrollbar[data-orientation="horizontal"] {
  width: auto;
  height: 12px;
}

.scroll-thumb {
  background: rgba(0, 0, 0, 0.5);
  border-radius: 6px;
  height: var(--scroll-area-thumb-height);
  width: 100%;
  transition: background 150ms;
}

.scroll-scrollbar[data-orientation="horizontal"] .scroll-thumb {
  width: var(--scroll-area-thumb-width);
  height: 100%;
}

.scroll-thumb:hover {
  background: rgba(0, 0, 0, 0.7);
}

.scroll-corner {
  background: rgba(0, 0, 0, 0.1);
}

Overflow Edge Detection

Use overflow edge thresholds to trigger visual indicators when content can be scrolled:

<ScrollArea.Root 
  overflowEdgeThreshold={50}
  className="scroll-area"
>
  <ScrollArea.Viewport>
    Content...
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar orientation="vertical">
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
</ScrollArea.Root>

/* Show fade when there's more content to scroll */
.scroll-area[data-overflow-y-end]::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
  height: 40px;
  background: linear-gradient(transparent, white);
  pointer-events: none;
}

CSS Variables

The component provides CSS variables for dynamic styling:

--scroll-area-thumb-height - Height of vertical thumb in pixels
--scroll-area-thumb-width - Width of horizontal thumb in pixels
--scroll-area-corner-height - Height of corner element in pixels
--scroll-area-corner-width - Width of corner element in pixels
--scroll-area-overflow-x-start - Distance scrolled from start (horizontal)
--scroll-area-overflow-x-end - Distance remaining to end (horizontal)
--scroll-area-overflow-y-start - Distance scrolled from start (vertical)
--scroll-area-overflow-y-end - Distance remaining to end (vertical)

Getting Started

Handbook

Inputs

Data Display

Navigation

Overlays

Forms

Layout

Utilities

Import

Basic Usage

Key Features

Components

ScrollArea.Root

ScrollArea.Viewport

ScrollArea.Scrollbar

ScrollArea.Thumb

ScrollArea.Corner

Styling Example

Overflow Edge Detection

CSS Variables

​Import

​Basic Usage

​Key Features

​Components

​ScrollArea.Root

​ScrollArea.Viewport

​ScrollArea.Scrollbar

​ScrollArea.Thumb

​ScrollArea.Corner

​Styling Example

​Overflow Edge Detection

​CSS Variables

Import

Basic Usage

Key Features

Components

ScrollArea.Root

ScrollArea.Viewport

ScrollArea.Scrollbar

ScrollArea.Thumb

ScrollArea.Corner

Styling Example

Overflow Edge Detection

CSS Variables