> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# ScrollArea

Data Display`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Provides a styled scroll container for overflow content.

## When to use

Use ScrollArea when a fixed region needs overflow behavior without changing page scroll.

**Recommended**

- Constrain height explicitly.
- Avoid hiding important actions below a small scroll region.

**Avoid**

- Do not use the component outside its intended interaction model.

## Examples


### Basic usage
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

function ScrollAreaExample() {
  return (
    <ScrollArea
      maxHeight={180}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 8,
      }}
    >
      <div style={{ padding: 16 }}>
        {Array.from({ length: 12 }, (_, index) => (
          <p key={index}>Activity item {index + 1}</p>
        ))}
      </div>
    </ScrollArea>
  );
}

export default ScrollAreaExample;
```

### Horizontal and two-axis scrolling
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

function ScrollDirections() {
  return (
    <Stack gap="lg">
      <ScrollArea direction="horizontal" maxWidth={400}>
        <div style={{ width: 760, padding: 16, whiteSpace: 'nowrap' }}>
          A long horizontal timeline that remains inside its own scroll area.
        </div>
      </ScrollArea>
      <ScrollArea direction="both" maxWidth={360} maxHeight={140}>
        <div style={{ width: 680, height: 260, padding: 16 }}>
          Content that can scroll on both axes.
        </div>
      </ScrollArea>
    </Stack>
  );
}

export default ScrollDirections;
```

### Persistent scrollbars and custom size
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

function ScrollbarStyles() {
  const content = Array.from({ length: 10 }, (_, index) => (
    <p key={index}>Scrollable row {index + 1}</p>
  ));

  return (
    <Stack direction="horizontal" gap="lg">
      <ScrollArea type="always" scrollbarSize={4} maxHeight={160}>
        <div style={{ padding: 12 }}>{content}</div>
      </ScrollArea>
      <ScrollArea type="always" scrollbarSize={10} maxHeight={160}>
        <div style={{ padding: 12 }}>{content}</div>
      </ScrollArea>
    </Stack>
  );
}

export default ScrollbarStyles;
```

### Horizontal scrolling
Constrain the available width and use the appropriate scrollbar orientation for horizontal content.
```tsx preview
import { ScrollArea, Tag } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaHorizontal() {
  return (
    <ScrollArea
      direction="horizontal"
      maxWidth={400}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div
        style={{ display: 'flex', gap: 8, padding: 16, width: 'max-content' }}
      >
        {items.slice(0, 20).map((item) => (
          <Tag key={item} color="primary">
            {item}
          </Tag>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### Both axes
Scroll each axis when content exceeds both dimensions without widening the page.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaBoth() {
  return (
    <ScrollArea
      direction="both"
      maxHeight={200}
      maxWidth={300}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ width: 600, padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
              whiteSpace: 'nowrap',
            }}
          >
            {item} — This is a long line that overflows the container
            horizontally to demonstrate both scrollbars.
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### Persistent scrollbars
`type="always"` retains the scrollbar track when scrollability should be more visible.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaAlwaysVisible() {
  return (
    <ScrollArea
      type="always"
      maxHeight={200}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### Scroll edge shadows
Edge shadows indicate hidden content and disappear when that edge is reached.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaWithShadow() {
  return (
    <ScrollArea
      scrollShadow
      maxHeight={200}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div style={{ padding: 16 }}>
        {items.map((item) => (
          <p
            key={item}
            style={{
              margin: '0 0 8px',
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </p>
        ))}
      </div>
    </ScrollArea>
  );
}
```

### Scrollbar size
Adjust scrollbar thickness while keeping the content area bounded.
```tsx preview
import { ScrollArea, Stack } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaCustomSize() {
  return (
    <Stack gap="lg">
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          Thin (4px)
        </p>
        <ScrollArea
          type="always"
          scrollbarSize={4}
          maxHeight={150}
          style={{
            border: '1px solid var(--tao-color-border-secondary)',
            borderRadius: 6,
          }}
        >
          <div style={{ padding: 16 }}>
            {items.slice(0, 30).map((item) => (
              <p
                key={item}
                style={{
                  margin: '0 0 8px',
                  color: 'var(--tao-color-text-secondary)',
                }}
              >
                {item}
              </p>
            ))}
          </div>
        </ScrollArea>
      </div>
      <div>
        <p
          style={{
            fontSize: 13,
            color: 'var(--tao-color-text-secondary)',
            marginBottom: 8,
          }}
        >
          Thick (10px)
        </p>
        <ScrollArea
          type="always"
          scrollbarSize={10}
          maxHeight={150}
          style={{
            border: '1px solid var(--tao-color-border-secondary)',
            borderRadius: 6,
          }}
        >
          <div style={{ padding: 16 }}>
            {items.slice(0, 30).map((item) => (
              <p
                key={item}
                style={{
                  margin: '0 0 8px',
                  color: 'var(--tao-color-text-secondary)',
                }}
              >
                {item}
              </p>
            ))}
          </div>
        </ScrollArea>
      </div>
    </Stack>
  );
}
```

### Horizontal edge shadows
Use side shadows to indicate additional content while scrolling horizontally.
```tsx preview
import { ScrollArea } from '@rockshin/tao-ui';

const items = Array.from({ length: 50 }, (_, i) => `Item ${i + 1}`);

export default function ScrollAreaHorizontalShadow() {
  return (
    <ScrollArea
      direction="horizontal"
      scrollShadow
      maxWidth={400}
      style={{
        border: '1px solid var(--tao-color-border-secondary)',
        borderRadius: 6,
      }}
    >
      <div
        style={{ display: 'flex', gap: 8, padding: 16, width: 'max-content' }}
      >
        {items.slice(0, 30).map((item) => (
          <div
            key={item}
            style={{
              flexShrink: 0,
              width: 100,
              height: 60,
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              background: 'var(--tao-color-fill-quaternary)',
              borderRadius: 6,
              fontSize: 13,
              color: 'var(--tao-color-text-secondary)',
            }}
          >
            {item}
          </div>
        ))}
      </div>
    </ScrollArea>
  );
}
```

## API


### [#](#scrollarea)ScrollArea



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| type | Scrollbar visibility behavior | `ScrollAreaType | undefined` | `hover` |
| direction | Scroll direction | `"vertical" | "horizontal" | "both" | undefined` | `vertical` |
| maxHeight | Max height — enables vertical scroll | `string | number | undefined` | `-` |
| maxWidth | Max width — enables horizontal scroll | `string | number | undefined` | `-` |
| scrollbarSize | Scrollbar size in px | `number | undefined` | `6` |
| scrollbarOffset | Offset from edges in px | `number | undefined` | `2` |
| scrollShadow | Show scroll shadows at edges | `boolean | undefined` | `-` |
| onScroll | Callback on scroll | `((e: UIEvent<HTMLDivElement, UIEvent>) => void) | undefined` | `-` |
| onScrollEnd | Callback when scrolled to bottom (threshold in px) | `(() => void) | undefined` | `-` |
| scrollEndThreshold | Threshold in px for onScrollEnd | `number | undefined` | `10` |
| className | Additional css class | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |

