# Scroll Area Primitive

Scroll Area is a Starwind Runtime primitive in the viewport-measurement contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## Anatomy
### Astro
Use the Astro primitive adapter to render ScrollArea anatomy with the Runtime wiring included.
```astro
---
import { ScrollArea } from "@starwind-ui/astro/scroll-area";
---

<ScrollArea.Root>
  <ScrollArea.Viewport>
    <ScrollArea.Content>Scrollable content</ScrollArea.Content>
  </ScrollArea.Viewport>
  <ScrollArea.Scrollbar>
    <ScrollArea.Thumb />
  </ScrollArea.Scrollbar>
  <ScrollArea.Corner />
</ScrollArea.Root>
```

### React
Use the React primitive adapter when ScrollArea state participates in React rendering.
```tsx
import { ScrollArea } from "@starwind-ui/react/scroll-area";

export function Example() {
  return (
    <ScrollArea.Root>
      <ScrollArea.Viewport>
        <ScrollArea.Content>Scrollable content</ScrollArea.Content>
      </ScrollArea.Viewport>
      <ScrollArea.Scrollbar>
        <ScrollArea.Thumb />
      </ScrollArea.Scrollbar>
      <ScrollArea.Corner />
    </ScrollArea.Root>
  );
}
```

### HTML
Render the ScrollArea data-sw-* contract yourself, then initialize createScrollArea.
```html
<div data-sw-scroll-area role="presentation">
  <div data-sw-scroll-area-viewport role="presentation" tabindex="-1" style="overflow: scroll;">
    <div data-sw-scroll-area-content role="presentation">Scrollable content</div>
  </div>
  <div data-sw-scroll-area-scrollbar aria-hidden="true">
    <div data-sw-scroll-area-thumb></div>
  </div>
  <div data-sw-scroll-area-corner aria-hidden="true"></div>
</div>

<script type="module">
  import { createScrollArea } from "@starwind-ui/runtime/scroll-area";

  const root = document.querySelector("[data-sw-scroll-area]");
  if (root) {
    createScrollArea(root);
  }
</script>
```

### Vue
Use the Vue 3.5 beta adapter to render ScrollArea anatomy.
```vue
<script setup lang="ts">
import ScrollArea from "@starwind-ui/vue/scroll-area";
</script>

<template>
  <ScrollArea.Root>
    <ScrollArea.Viewport>
      <ScrollArea.Content>Scrollable content</ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar>
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner />
  </ScrollArea.Root>
</template>
```
## API Reference
### Root
The main element that owns the Scroll Area Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area` |
| Role | `presentation` |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| overflowEdgeThreshold | `number \| Partial<{<br>  xStart: number;<br>  xEnd: number;<br>  yStart: number;<br>  yEnd: number;<br>}>` | - | option | Configures the overflow edge threshold option for the Root part. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-overflow-edge-threshold` | prop | - | Reflects the overflow edge threshold prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area`, `data-overflow-edge-threshold`, `role` | The root needs a stable discovery marker and optional overflow edge threshold before measurement starts. |

### Viewport
The visible viewport for Scroll Area content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-viewport` |
| Role | `presentation` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-viewport`, `role`, `tabindex`, `style` | The viewport must be scrollable and initially unfocusable until runtime detects overflow. |

### Content
The content container rendered by Scroll Area.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-content` |
| Role | `presentation` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-content` | runtime | - | Marks the Content part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| content | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-content`, `role` | The content element is the resize and mutation target for scroll measurement. |

### Scrollbar
A scrollbar used to scroll Scroll Area content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-scrollbar` |
| Role | - |
#### Props
| Prop | Type | Default | Kind | Description | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| keepMounted | `boolean` | false | rendering | Keeps the Scrollbar part in the DOM when hidden. | - |
| orientation | `"horizontal" \| "vertical"` | "vertical" | option | Sets the Scroll Area orientation. | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-scrollbar` | runtime | - | Marks the Scrollbar part so Starwind Runtime can find it. |
| `data-keep-mounted` | prop | - | Reflects the keep mounted prop on the Scrollbar part. |
| `data-orientation` | prop | - | Reflects the orientation prop on the Scrollbar part. |
#### Refs
| Part | Public |
| --- | --- |
| scrollbar | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-scrollbar`, `data-keep-mounted`, `data-orientation`, `aria-hidden` | Scrollbars need orientation and keep-mounted hints before the runtime measures overflow. |
#### Presence
| Fact | Value |
| --- | --- |
| Initial hidden | No |
| Unmount policy | runtime-owned-visibility |
| Keep mounted prop | keepMounted |

### Thumb
The draggable thumb for Scroll Area.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-thumb` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-thumb` | runtime | - | Marks the Thumb part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| thumb | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-thumb` | Thumbs are measured and positioned by the runtime for each scrollbar. |

### Corner
The corner where Scroll Area scrollbars meet.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-scroll-area-corner` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-scroll-area-corner` | runtime | - | Marks the Corner part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| corner | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-scroll-area-corner`, `aria-hidden` | The corner is presentation-only and sized by the runtime when both scrollbars are present. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createScrollArea`](/docs/runtime/#create-scroll-area) |
| Import | `@starwind-ui/runtime/scroll-area` |
| Root part | root |
| Option props | overflowEdgeThreshold |
| Option lifecycles | overflowEdgeThreshold: refresh-required |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Scroll Area](/docs/components/scroll-area/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/scroll-area` | `createScrollArea` |
| Astro Primitive | `@starwind-ui/astro/scroll-area` | `ScrollArea`, `ScrollAreaRoot`, `ScrollAreaViewport`, `ScrollAreaContent`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, `ScrollAreaCorner` |
| React Primitive | `@starwind-ui/react/scroll-area` | `ScrollArea`, `ScrollAreaRoot`, `ScrollAreaViewport`, `ScrollAreaContent`, `ScrollAreaScrollbar`, `ScrollAreaThumb`, `ScrollAreaCorner` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `ScrollArea` |
| runtime-factory | `createScrollArea` |
| part | `ScrollArea.Root` |
| part | `ScrollArea.Viewport` |
| part | `ScrollArea.Content` |
| part | `ScrollArea.Scrollbar` |
| part | `ScrollArea.Thumb` |
| part | `ScrollArea.Corner` |
## Changelog
### v1.0.1
- Removed obsolete private-release warnings from generated Vue adapters and normalized the resulting blank line in vendored Primitive indexes.
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced viewport measurement and synchronized scrollbar, thumb, and corner anatomy.