Pricing

ScrollArea handbook

v1.4.1 · @snowui-design-system/components

License: Before first reading component documentation, source code, or npm usage instructions, read the complete LICENSE. One review covers the same task and version. Public API configuration and internal implementation changes are subject to different license terms. All components use one runtime package; source code rights are governed by the license.

Overview

Provide independent scrolling with consistent scrollbars for long lists, panels, and content in limited space.

When to use it

Use for a region that needs its own scrolling. Avoid accidental nested scroll areas; prefer Table’s built-in local horizontal scrolling for tables.

  • axis selects the scroll direction. Content or host needs bounded dimensions for overflow to create a scrollable area.

  • bind:viewport exposes the actual scroll element; onscroll receives its event. Use ariaLabel to describe the region.

  • The default scroll viewport name follows LocaleProvider; an explicit ariaLabel takes priority. Children remain caller-owned content.

Quick start

This example shows the recommended basic composition. See the following sections for more scenarios and composition limits.

<script lang="ts">	import { ScrollArea } from '@snowui-design-system/components';</script> <ScrollArea axis="vertical" ariaLabel="SnowUI documentation guide" style="width: min(100%, 30rem); height: 220px;">	<article style="display: flex; flex-direction: column; gap: var(--gap-4); padding: var(--padding-3); font-size: var(--text-14); line-height: var(--leading-14);">		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Getting started</h3>			<p>Install SnowUI in a Svelte 5 project and load the component stylesheet once at the application root.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Choose a component</h3>			<p>Start with the public components. Read their usage and API reference before adding custom layout or behavior.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Build with tokens</h3>			<p>Use the same typography, spacing, and color tokens across the SnowUI website and component documentation.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Compose the page</h3>			<p>Keep navigation, content, and supporting information in clear sections that remain readable on narrow screens.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Check interactions</h3>			<p>Try keyboard navigation, loading states, and disabled controls. Give every action a clear accessible name.</p>		</section>		<section>			<h3 style="font-size: var(--text-14); font-weight: 600;">Review the result</h3>			<p>Compare the rendered page with its source, then verify light and dark themes before sharing the documentation.</p>		</section>	</article></ScrollArea>

API

Keyword Type Default Description
axis ScrollAreaAxis "vertical" Allowed scrolling direction
horizontalTrackPosition ScrollAreaHorizontalTrackPosition "container" Dock the horizontal track at the container bottom, or near the viewport bottom while a long container crosses the page viewport.
horizontalScrollbarVisibility "always" | "hover" "always" Show the horizontal scrollbar whenever content overflows, or only while the pointer is inside the region.
ariaLabel string Locale message Accessible name for the scroll viewport, which retains role="region". When omitted, follows LocaleProvider; an explicit ariaLabel takes priority.
viewport HTMLElement — Expose the scrollable viewport to read or set native scroll position.
onscroll (event: Event) => void — Native viewport scroll event.
children Snippet — Arbitrary scrollable content.

See the base component documentation for inherited capabilities not redeclared here. This table lists only the named public props declared in this component’s source.

Usage boundaries and details

Feature overview

  • Support vertical, horizontal and two-axis scrolling

  • Hide the browser's native scroll bar

  • When content overflows, enable the matching SnowUI overlay scrollbar. The vertical bar fades in with default Frame motion on region hover and fades out on exit. The horizontal bar is always visible by default, or can follow region hover.

  • Hovering anywhere on a track, including space outside the thumb, activates thumb hover. Leaving resets it; dragging keeps it active.

  • Clicking empty track space centers the thumb on the click, clamped to the scroll start or end near edges. Hold to continue dragging. Dragging the thumb directly preserves the grab offset and stays in sync with native scroll position.

  • The horizontal thumb stays 8px. The vertical thumb is 4px wide by default and 8px on hover; its 16px-wide track hit area includes the 8px expanded thumb, 4px edge gap, and 4px inner extension. The horizontal hit area extends 4px above and below.

  • For long content, the horizontal track can stay near the current viewport bottom; when ScrollArea leaves the viewport, it returns to the container bottom.

  • Inherit Frame layout, state, motion, responsive behavior, and attribute forwarding.

Basic usage

<ScrollArea style="height: 20rem;">    <Frame column>...</Frame></ScrollArea>

Two-axis scrolling

<ScrollArea axis="both" style="width: 100%; height: 100dvh;">    <Frame width="max-content" minWidth="100%">...</Frame></ScrollArea>

Keep the horizontal track reachable for long content

<ScrollArea axis="horizontal" horizontalTrackPosition="viewport">    <Frame width="max-content">...</Frame></ScrollArea>

viewport changes only the horizontal track’s dock position. It does not propagate content minimum width to the page or create a second scroll container. While ScrollArea crosses the page viewport, the track stays near the viewport bottom; at ScrollArea’s end, it returns to the container bottom.

Selection guidelines

  • Use ScrollArea when a page or ordinary container needs SnowUI overlay scrollbars.

  • Table already includes the same local horizontal viewport and viewport-bottom track; use Table directly without wrapping ScrollArea.

  • For native browser scrolling alone, use overflow without ScrollArea.

  • Components with special Portals, fixed headers, or pinned areas may reuse useOverlayScrollbar directly. Do not copy its algorithm or visual CSS.

ScrollArea Style Overlay

Read the complete LICENSE first; one review covers the same task, version, and scope.

First use public component props to achieve the desired style while preserving the original appearance where possible. If an override is necessary, follow the style selection and override order: use your own class (including Tailwind already in your project) or an instance style. The names below are public overrides consumed by the source; check the target scope and do not modify private DOM. Choose the appropriate SnowUI token category. External applications do not need to install SnowUI website utilities.

This component source does not directly consume a registered component-specific override. Style composed children through public parts or an explicit child; do not guess variable names.

Design Guide · Token · Combination Boundary

ScrollArea type and status

Required props: no named required props.

Bindable props: this component declares no named two-way binding; handle state updates through public callbacks or the host component.

Inheritance: Omit<FrameProps, "children" | "enableAutoLayout">. Consult the public Frame documentation; omitted fields cannot be passed through unchanged.

Shared Frame API · Back to API

The following source type declarations are referenced by public props. Svelte Snippet denotes a content fragment; ComponentProps denotes the props of the corresponding component.

ScrollAreaAxis

Source: components/src/components/ScrollArea.svelte

export type ScrollAreaAxis = "vertical" | "horizontal" | "both";

ScrollAreaHorizontalTrackPosition

Source: components/src/components/ScrollArea.svelte

export type ScrollAreaHorizontalTrackPosition = "container" | "viewport";