## Overview [#overview]
The `ScrollArea` component provides a scrollable viewport with custom scrollbars and optional edge shadows. It does not paint its own surface by default; put it inside the surface that owns the frame.
Scrollbar styling is surface-aware. Tracks land two levels above the current surface and thumbs land four levels above the current surface. Scroll shadows default to the current surface color, so a scroll area inside `Card` automatically fades to the card surface.
## Usage [#usage]
```tsx
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
```
```tsx
{/* Scrollable content */}
```
## Examples [#examples]
### Basic [#basic]
A vertical scroll area inside a card. The card owns the surface and the scroll content owns the padding.
```tsx
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
import { Separator } from "@tilt-legal/cubitt-components/separator";
export default function Example() {
const tags = Array.from(
{ length: 50 },
(_, index) => `v1.2.0-beta.${50 - index}`
);
return (
Tags
{tags.map((tag) => (
{tag}
))}
);
}
```
### Horizontal [#horizontal]
Set `orientation="horizontal"` for horizontal overflow.
```tsx
import type { CSSProperties } from "react";
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
const scrollbarInsetStyle = {
"--scrollbar-inset-left": "1rem",
"--scrollbar-inset-right": "1rem",
} as CSSProperties;
export default function Example() {
const artworks = [
{ artist: "Ornella Binni" },
{ artist: "Tom Byrom" },
{ artist: "Vladimir Malyavko" },
];
return (
{artworks.map((artwork) => (
Photo by{" "}
{artwork.artist}
))}
);
}
```
### Both Directions [#both-directions]
Set `orientation="both"` when content can overflow on both axes.
```tsx
import type { CSSProperties } from "react";
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
const scrollbarInsetStyle = {
"--scrollbar-inset-left": "1rem",
"--scrollbar-inset-right": "1rem",
} as CSSProperties;
export default function Example() {
return (
{Array.from({ length: 20 }).map((_, index) => (
))}
);
}
```
### Scroll Shadows [#scroll-shadows]
Use `scrollShadow` to show edge gradients when more content is available.
```tsx
import type { CSSProperties } from "react";
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
const scrollbarInsetStyle = {
"--scrollbar-inset-left": "1rem",
"--scrollbar-inset-right": "1rem",
} as CSSProperties;
export default function Example() {
return (
{/* Wide and tall content */}
);
}
```
### Custom Shadow [#custom-shadow]
Fine-tune shadow size, opacity, stop position, snap behavior, and color.
```tsx
import { Card } from "@tilt-legal/cubitt-components/card";
import {
ScrollArea,
ScrollAreaContent,
} from "@tilt-legal/cubitt-components/scroll-area";
export default function Example() {
return (
{/* Scrollable content */}
);
}
```
## API Reference [#api-reference]
### ScrollArea [#scrollarea]
The root scrollable container component.
| Prop | Type | Default | Description |
| -------------- | ------------------------------------------------------------------------------------ | ------------ | ------------------------------------ |
| `orientation` | `"vertical"` \| `"horizontal"` \| `"both"` | `"vertical"` | Direction of scrolling. |
| `scrollShadow` | `"vertical"` \| `"horizontal"` \| `"both"` \| `"none"` \| `ScrollShadowObjectConfig` | `"none"` | Optional edge shadow configuration. |
| `className` | `string` | — | Additional classes for the viewport. |
### ScrollShadowConfig [#scrollshadowconfig]
| Property | Type | Default | Description |
| ------------- | --------- | --------------- | ------------------------------------------------------------------------ |
| `size` | `string` | `"40px"` | Size of the shadow gradient. |
| `color` | `string` | Current surface | CSS color used for the gradient. |
| `stopPercent` | `number` | `0` | Percentage where the solid color ends and fading begins. |
| `stopOpacity` | `number` | `100` | Opacity of the intermediate color stop before fading to transparent. |
| `snap` | `boolean` | `false` | When true, the shadow appears at full size instead of growing gradually. |
### ScrollShadowObjectConfig [#scrollshadowobjectconfig]
The object configuration supports axis shortcuts or individual sides. Do not mix an axis shortcut with that axis' side-specific keys.
| Property | Type | Description |
| ------------ | --------------------------------- | ----------------------------------------------- |
| `vertical` | `boolean` \| `ScrollShadowConfig` | Shortcut for top and bottom shadows. |
| `horizontal` | `boolean` \| `ScrollShadowConfig` | Shortcut for left and right shadows. |
| `top` | `boolean` \| `ScrollShadowConfig` | Top shadow. Cannot be used with `vertical`. |
| `bottom` | `boolean` \| `ScrollShadowConfig` | Bottom shadow. Cannot be used with `vertical`. |
| `left` | `boolean` \| `ScrollShadowConfig` | Left shadow. Cannot be used with `horizontal`. |
| `right` | `boolean` \| `ScrollShadowConfig` | Right shadow. Cannot be used with `horizontal`. |
### ScrollAreaContent [#scrollareacontent]
Container for the scrollable content.
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | --------------------------------------------- |
| `className` | `string` | — | Additional classes for the content container. |
### ScrollBar [#scrollbar]
Custom scrollbar component used internally by `ScrollArea`.
| Prop | Type | Default | Description |
| ------------- | ------------------------------ | ------------ | --------------------------------- |
| `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | Direction of the scrollbar. |
| `className` | `string` | — | Additional classes for the track. |
### CSS Custom Properties [#css-custom-properties]
Scrollbar inset variables are orientation-specific. Vertical scrollbars read the top and bottom variables; horizontal scrollbars read the left and right variables.
| Variable | Default | Description |
| -------------------------- | ------- | ------------------------------------------------ |
| `--scrollbar-inset-top` | `1rem` | Top inset used by vertical scrollbar tracks. |
| `--scrollbar-inset-bottom` | `1rem` | Bottom inset used by vertical scrollbar tracks. |
| `--scrollbar-inset-left` | `0rem` | Left inset used by horizontal scrollbar tracks. |
| `--scrollbar-inset-right` | `0rem` | Right inset used by horizontal scrollbar tracks. |