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
Use the Astro primitive adapter to render ScrollArea anatomy with the Runtime wiring included.
---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>Use the React primitive adapter when ScrollArea state participates in React rendering.
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> );}Render the ScrollArea data-sw-* contract yourself, then initialize createScrollArea.
<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>API Reference
Root
The main element that owns the Scroll Area Runtime instance.
- Default element
- div
- Discovery hook
- data-sw-scroll-area
- Role
- presentation
Props
Prop Type Default Toggle
overflowEdgeThreshold number | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }> -
- Description
- Configures the overflow edge threshold option for the Root part.
- Kind
- option
- Targets
- root
- Full type
- number | Partial<{ xStart: number; xEnd: number; yStart: number; yEnd: number; }>
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area - Marks the Root part so Starwind Runtime can find it.
Metadata
Attribute Value Description
data-overflow-edge-threshold - Reflects the overflow edge threshold prop on the Root part.
Viewport
The visible viewport for Scroll Area content.
- Default element
- div
- Discovery hook
- data-sw-scroll-area-viewport
- Role
- presentation
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area-viewport - Marks the Viewport part so Starwind Runtime can find it.
Content
The content container rendered by Scroll Area.
- Default element
- div
- Discovery hook
- data-sw-scroll-area-content
- Role
- presentation
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area-content - Marks the Content part so Starwind Runtime can find it.
Scrollbar
A scrollbar used to scroll Scroll Area content.
- Default element
- div
- Discovery hook
- data-sw-scroll-area-scrollbar
- Role
- -
Props
Prop Type Default Toggle
keepMounted boolean false
- Description
- Keeps the Scrollbar part in the DOM when hidden.
- Kind
- rendering
- Targets
- scrollbar
- Full type
- boolean
orientation "horizontal" | "vertical" "vertical"
- Description
- Sets the Scroll Area orientation.
- Kind
- option
- Targets
- scrollbar
- Full type
- "horizontal" | "vertical"
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area-scrollbar - Marks the Scrollbar part so Starwind Runtime can find it.
Metadata
Attribute Value Description
data-keep-mounted - Reflects the keep mounted prop on the Scrollbar part.
data-orientation - Reflects the orientation prop on the Scrollbar part.
Thumb
The draggable thumb for Scroll Area.
- Default element
- div
- Discovery hook
- data-sw-scroll-area-thumb
- Role
- -
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area-thumb - Marks the Thumb part so Starwind Runtime can find it.
Corner
The corner where Scroll Area scrollbars meet.
- Default element
- div
- Discovery hook
- data-sw-scroll-area-corner
- Role
- -
Data Attributes
Runtime hooks
Attribute Value Description
data-sw-scroll-area-corner - Marks the Corner part so Starwind Runtime can find it.
Runtime API
- Factory
createScrollArea- Import
@starwind-ui/runtime/scroll-area- Root hook
- root
data-sw-scroll-area - Option props
- overflowEdgeThreshold
Option Lifecycles
| Option | Lifecycle |
|---|---|
| overflowEdgeThreshold | refresh-required |
Related Styled Components
Component Relationship
Scroll Area Direct primitive
Changelog
View version history v1.0.0 3 releases
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.