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.
Consumed interfaces
IScrollProps
IScrollArguments
IScrollStrategyProps
IScrollStrategyData
API
Parameters
Input parameters accepted by this composable.
- propsrequiredIScrollProps
- 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).
- argsIScrollArguments{}
- 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
Custom scroll ratio indicator
Scroll strategy on a floating overlay