scroll

Track the scroll offset, edges, and direction of an element or window.


Package	`@vizejs/composable/scroll`
Own the source	`vize lib pull composable:scroll`
Runtime exports	`useScroll`, `useWindowScroll`
Gzip budget	3072 B

Usage

import { useScroll, useWindowScroll } from "@vizejs/composable/scroll";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useScroll`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`	`isElementNode`, `resolveElement`, `tryOnScopeDispose`
`useWindowScroll`	dom	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`globalThis`, `window`	`useScroll`

API

`useScroll`

Track the scroll offset, edges, and direction of an element or window. During server rendering (or while the target is unresolved) offsets are 0, the top/left edges report arrived, and the bottom/right edges do not — matching an unscrolled page, so hydration is stable. The scroll listener is passive and removed together with the idle timer when the owning reactive scope stops. Inside a component the host is read after mounting, so hydration renders the server fallback first and never mismatches.

function useScroll( target: MaybeRefOrGetter<ScrollTargetValue>, options: UseScrollOptions = {}, ): ScrollControls

`useWindowScroll`

Track the document scroll position. Equivalent to useScroll with the window as target, so it shares its SSR-stable defaults and scope-bound cleanup.

function useWindowScroll(options: UseWindowScrollOptions = {}): ScrollControls

Types

`ScrollMetrics`

Scroll extents shared by elements and the document root element.

Member	Type	Description
`scrollWidth`	`number`	Total scrollable width.
`scrollHeight`	`number`	Total scrollable height.
`clientWidth`	`number`	Visible width without scrollbars.
`clientHeight`	`number`	Visible height without scrollbars.

`ScrollWindowHost`

Window-like scroll container accepted by useScroll.

Member	Type	Description
`scrollX`	`number`	Horizontal document scroll offset.
`scrollY`	`number`	Vertical document scroll offset.
`scrollTo`	`(options: ScrollToOptions) => void`	Scroll the document.
`document`	`{ readonly documentElement: ScrollMetrics }`	Document whose root element reports the scroll extents.

`ScrollEdges`

Per-edge boolean state.

Member	Type	Description
`left`	`boolean`	Left edge (or inline start in LTR).
`right`	`boolean`	Right edge.
`top`	`boolean`	Top edge.
`bottom`	`boolean`	Bottom edge.

`ScrollOffset`

Per-edge distance thresholds in CSS pixels.

Member	Type	Description
`left`?	`number`	Distance from the left edge that still counts as arrived.
`right`?	`number`	Distance from the right edge that still counts as arrived.
`top`?	`number`	Distance from the top edge that still counts as arrived.
`bottom`?	`number`	Distance from the bottom edge that still counts as arrived.

`UseScrollOptions`

Options for useScroll.

Member	Type	Description
`offset`?	`ScrollOffset`	Edge tolerances used to compute `arrivedState`.
`idle`?	`number`	Milliseconds without scroll events before `isScrolling` becomes `false` (used when the engine does not fire `scrollend`).
`behavior`?	`MaybeRefOrGetter<ScrollBehavior>`	Scroll behavior used by `scrollTo` and the writable `x`/`y` refs.
`onScroll`?	`(event: Event) => void`	Called for every scroll event after the state has been updated.
`onStop`?	`(event: Event) => void`	Called once scrolling settles.
`scheduler`?	`TimeoutScheduler`	Owns the idle timer.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.

`ScrollControls`

Reactive scroll state returned by useScroll.

Member	Type	Description
`x`	`WritableComputedRef<number>`	Horizontal offset. Assigning scrolls the target with the configured behavior.
`y`	`WritableComputedRef<number>`	Vertical offset. Assigning scrolls the target with the configured behavior.
`isScrolling`	`Readonly<Ref<boolean>>`	Whether scroll events arrived within the idle window.
`arrivedState`	`Readonly<ScrollEdges>`	Whether each edge has been reached (within `offset`).
`directions`	`Readonly<ScrollEdges>`	Direction of the most recent scroll movement; reset when scrolling stops.
`measure`	`() => void`	Re-read offsets and edges without waiting for a scroll event.
`scrollTo`	`(options: { readonly left?: number; readonly top?: number }) => void`	Scroll the target. Missing axes keep their current offset.

`UseWindowScrollOptions`

Options for useWindowScroll.

Member	Type	Description
`offset`?	`ScrollOffset`	Edge tolerances used to compute `arrivedState`.
`idle`?	`number`	Milliseconds without scroll events before `isScrolling` becomes `false` (used when the engine does not fire `scrollend`).
`behavior`?	`MaybeRefOrGetter<ScrollBehavior>`	Scroll behavior used by `scrollTo` and the writable `x`/`y` refs.
`onScroll`?	`(event: Event) => void`	Called for every scroll event after the state has been updated.
`onStop`?	`(event: Event) => void`	Called once scrolling settles.
`scheduler`?	`TimeoutScheduler`	Owns the idle timer.
`flush`?	`"pre" \| "post" \| "sync"`	Target resolution timing. `"post"` observes template refs after mount.
`host`?	`MaybeRefOrGetter<ScrollWindowHost \| null \| undefined>`	Reactive window capability for alternate runtimes and tests.