useScrollPosition
Layout & observersTrack the throttled scroll offset (x, y) of the window or a given element
Install
$ npm install @usefy/use-scroll-positionQuick start
useScrollPosition.tsx
import { useScrollPosition } from "@usefy/use-scroll-position";
function ScrollIndicator() {
const { x, y } = useScrollPosition();
return <div>Scrolled to {x}, {y}</div>;
}API reference
useScrollPosition(options?)
Returns the current scroll offset of the tracked target, re-rendering (throttled) as it scrolls.
Options — UseScrollPositionOptions
| Option | Type | Default | Description |
|---|---|---|---|
element | HTMLElement | RefObject<HTMLElement> | null | window | The element (or a ref to it) whose scroll to track. Omit / null tracks the window/document |
throttleMs | number | 100 | Throttle interval in ms (leading + trailing). 0 updates on every scroll event (no throttle) |
Returns — UseScrollPositionReturn (ScrollPosition)
| Property | Type | Description |
|---|---|---|
x | number | Horizontal offset — window.scrollX or the element's scrollLeft |
y | number | Vertical offset — window.scrollY or the element's scrollTop |
Also exported: the ZERO_SCROLL_POSITION sentinel and the ScrollPosition, ScrollPositionTarget, UseScrollPositionOptions, and UseScrollPositionReturn types.
Go deeper
This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.