# Scroll Area

URL: https://ark-ui.com/docs/components/scroll-area
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/scroll-area.mdx

A custom scrollable area component with styled scrollbars.

---

<ComponentPreview id="ScrollArea" />

## Features

- Cross-browser custom scrollbars
- Native scroll behavior
- Keyboard navigation support
- Touch and mouse support
- Horizontal and vertical scrolling
- Support for nested scroll areas
- Customizable scrollbar appearance

## Anatomy

To set up the scroll area correctly, it's essential to understand its anatomy and the naming of its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="scroll-area" />

## Required style

It's important to note that the scroll area requires the following styles on the `ScrollArea.Viewport` element to hide
the native scrollbar:

```css
[data-scope='scroll-area'][data-part='viewport'] {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}
```

## Examples

### Basic Usage

Create a basic scrollable area with custom scrollbar.

<Example id="basic" />

### Horizontal Scrolling

Configure the scroll area for horizontal scrolling only.

<Example id="horizontal" />

### Both Directions

Enable scrolling in both horizontal and vertical directions.

<Example id="both-directions" />

### Nested Scroll Areas

Scroll areas can be nested within each other for complex layouts.

<Example id="nested" />

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | root |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | content |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Corner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Corner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | corner |
| `[data-hover]` | Present when hovered |
| `[data-state]` | "hidden" | "visible" |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseScrollAreaReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrollbar Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**Scrollbar Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | scrollbar |
| `[data-orientation]` | The orientation of the scrollbar |
| `[data-scrolling]` | Present when scrolling |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | thumb |
| `[data-orientation]` | The orientation of the thumb |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | viewport |
| `[data-at-top]` | Present when scrolled to the top edge |
| `[data-at-bottom]` | Present when scrolled to the bottom edge |
| `[data-at-left]` | Present when scrolled to the left edge |
| `[data-at-right]` | Present when scrolled to the right edge |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | root |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | content |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Corner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Corner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | corner |
| `[data-hover]` | Present when hovered |
| `[data-state]` | "hidden" | "visible" |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseScrollAreaContext` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrollbar Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**Scrollbar Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | scrollbar |
| `[data-orientation]` | The orientation of the scrollbar |
| `[data-scrolling]` | Present when scrolling |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | thumb |
| `[data-orientation]` | The orientation of the thumb |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | viewport |
| `[data-at-top]` | Present when scrolled to the top edge |
| `[data-at-bottom]` | Present when scrolled to the bottom edge |
| `[data-at-left]` | Present when scrolled to the left edge |
| `[data-at-right]` | Present when scrolled to the right edge |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | root |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | content |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Corner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Corner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | corner |
| `[data-hover]` | Present when hovered |
| `[data-state]` | "hidden" | "visible" |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `ScrollAreaApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Scrollbar Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |


**Scrollbar Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | scrollbar |
| `[data-orientation]` | The orientation of the scrollbar |
| `[data-scrolling]` | Present when scrolling |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | thumb |
| `[data-orientation]` | The orientation of the thumb |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | viewport |
| `[data-at-top]` | Present when scrolled to the top edge |
| `[data-at-bottom]` | Present when scrolled to the bottom edge |
| `[data-at-left]` | Present when scrolled to the left edge |
| `[data-at-right]` | Present when scrolled to the right edge |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>` | No | The ids of the scroll area elements |
| `ref` | `Element` | No |  |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | root |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | content |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseScrollAreaContext]>` | Yes |  |


**Corner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Corner Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | corner |
| `[data-hover]` | Present when hovered |
| `[data-state]` | "hidden" | "visible" |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseScrollAreaContext` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Scrollbar Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `orientation` | `Orientation` | No |  |
| `ref` | `Element` | No |  |


**Scrollbar Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | scrollbar |
| `[data-orientation]` | The orientation of the scrollbar |
| `[data-scrolling]` | Present when scrolling |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


**Thumb Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Thumb Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | thumb |
| `[data-orientation]` | The orientation of the thumb |
| `[data-hover]` | Present when hovered |
| `[data-dragging]` | Present when in the dragging state |


**Viewport Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Viewport Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | scroll-area |
| `[data-part]` | viewport |
| `[data-at-top]` | Present when scrolled to the top edge |
| `[data-at-bottom]` | Present when scrolled to the bottom edge |
| `[data-at-left]` | Present when scrolled to the left edge |
| `[data-at-right]` | Present when scrolled to the right edge |
| `[data-overflow-x]` | Present when the content overflows the x-axis |
| `[data-overflow-y]` | Present when the content overflows the y-axis |


### Context

These are the properties available when using `UscrollUarea.Context`, `useUscrollUareaContext` hook or `useUscrollUarea` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `isAtTop` | `boolean` | Whether the scroll area is at the top |
| `isAtBottom` | `boolean` | Whether the scroll area is at the bottom |
| `isAtLeft` | `boolean` | Whether the scroll area is at the left |
| `isAtRight` | `boolean` | Whether the scroll area is at the right |
| `hasOverflowX` | `boolean` | Whether the scroll area has horizontal overflow |
| `hasOverflowY` | `boolean` | Whether the scroll area has vertical overflow |
| `getScrollProgress` | `() => Point` | Get the scroll progress as values between 0 and 1 |
| `scrollToEdge` | `(details: ScrollToEdgeDetails) => void` | Scroll to the edge of the scroll area |
| `scrollTo` | `(details: ScrollToDetails) => void` | Scroll to specific coordinates |
| `getScrollbarState` | `(props: ScrollbarProps) => ScrollbarState` | Returns the state of the scrollbar |