useScroll

Commons
stable

Tracks scroll position and direction on a configurable target element (or window). Returns reactive flags for scroll direction, activity state, threshold crossing, and a scroll ratio useful for progressive UI transitions. Also exposes useScrollStrategies (apply named scroll behaviours like block, close, or reposition to floating overlays) and useScrolling (keyboard + scroll helpers for virtualised list + search-field combos).

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

Consumed interfaces

IScrollProps
IScrollArguments
IScrollStrategyProps
IScrollStrategyData

API

Parameters

Input parameters accepted by this composable.

props
required
IScrollProps
Props containing `scrollTarget` (CSS selector string for a custom scroll container, defaults to window) and `scrollThreshold` (pixel distance that must be crossed before scroll events activate).
args
IScrollArguments
{}
Optional arguments bag. `canScroll: Ref<boolean>` — when provided, scroll events are ignored while canScroll is false (used by layouts that conditionally enable scrolling).

API

Return values

Properties and methods exposed by the composable return object.

currentScroll
Current scroll position in pixels (scrollTop or pageYOffset).
isScrollingUp
True when the most recent scroll event moved upward.
isScrollActive
True while scrolling is actively happening. Used by app bars to hide/show.
scrollRatio
Normalised ratio: (scrollThreshold - currentScroll) / scrollThreshold, clamped to [0, 1]. 1 = at top, 0 = threshold crossed.
scrollThreshold
The threshold prop coerced to a number.
currentThreshold
Absolute distance between currentScroll and scrollThreshold.
savedScroll
Scroll position saved at the last direction reversal. Used by app-bar hide strategies.

Usage

Examples

Ready-to-paste usage snippets.

Auto-hide app bar on scroll

vue

Custom scroll ratio indicator

vue

Scroll strategy on a floating overlay

vue