useScroll

Tracks the scroll position, scroll direction, arrived state (top/bottom/left/right), and scrolling status of any scrollable target — HTMLElement, Document, or Window — as reactive Observable values.

Demo

x: 0y: 0idletopbottom

Item 1

Item 2

Item 3

Item 4

Item 5

Item 6

Item 7

Item 8

Item 9

Item 10

Item 11

Item 12

Item 13

Item 14

Item 15

Item 16

Item 17

Item 18

Item 19

Item 20

Scroll inside the box to see x, y, arrivedState, and directions update.

Usage

Hook

import { useScroll } from "@usels/web";
import { useRef$ } from "@usels/core";

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const { x$, y$, arrivedState$ } = useScroll(el$);

  return (
    <div ref={el$} style={{ overflow: "auto", height: 300 }}>
      <p>
        scrollX: {x$.get()}, scrollY: {y$.get()}
        {arrivedState$.bottom.get() && " — reached bottom"}
      </p>
    </div>
  );
}

Scope

import { createScroll } from "@usels/web";
import { createRef$ } from "@usels/core";

function Component() {
  "use scope"
  const el$ = createRef$<HTMLDivElement>();
  const { x$, y$, arrivedState$ } = createScroll(el$);

  return (
    <div ref={el$} style={{ overflow: "auto", height: 300 }}>
      <p>
        scrollX: {x$.get()}, scrollY: {y$.get()}
        {arrivedState$.bottom.get() && " — reached bottom"}
      </p>
    </div>
  );
}

Window scroll

Use useWindowScroll for the common case, or pass window directly.

import { useScroll } from "@usels/web";

function Component() {
  const { y$, arrivedState$, isScrolling$ } = useScroll(window);
}

Arrived state with offset

Use offset to declare a threshold (in px) before the edge is considered “arrived”.

const { arrivedState$ } = useScroll(el$, {
  offset: { bottom: 100 }, // bottom=true when within 100px of the end
});

isScrolling + onStop

const { isScrolling$ } = useScroll(el$, {
  idle: 300, // ms to wait before isScrolling becomes false (default: 200)
  onStop: () => {
    // called when scrolling stops
  },
});

Throttle

const { x$, y$ } = useScroll(el$, { throttle: 50 }); // handler fires at most once per 50ms

Manual re-measure

const { y$, measure } = useScroll(el$);

// Call measure() to force-sync scroll state without a scroll event
measure();

Reactive options

Options can be passed as plain values, per-field Observables, or a single Observable<UseScrollOptions>. Changes are picked up reactively.

import { observable } from "@usels/core";

const idle$ = observable(200);
const { isScrolling$ } = useScroll(el$, { idle: idle$ });

// Later: update idle time reactively
idle$.set(500);

Notes

Reactive observables, not state. All returned values (x$, y$, isScrolling$, arrivedState$, directions$) are Legend-State Observables. Read them with .get() inside a reactive context to avoid unnecessary re-renders.

measure() is synchronous. It immediately reads the current scroll values from the DOM and updates all observables. Useful after programmatic scroll operations.

arrivedState initial values. On mount, top and left default to true, and bottom/right default to false. After the first measure() call (triggered automatically on mount), all values are synced with actual DOM state.

options is DeepMaybeObservable. Each option field can be a plain value or an Observable. Callback options (onScroll, onStop, onError) are passed as plain functions.

Type

Parameters

Parameter	Type	Description
element	MaybeEventTarget<Element | Document | Window>	-
options	UseScrollOptions (optional)	-

UseScrollOptions

Option	Type	Default	Description
throttle	number	-	-
idle	number	-	-
onScroll	((e: Event) => void)	-	-
onStop	(() => void)	-	-
onError	((error: unknown) => void)	-	-
offset	{ left?: number | undefined; right?: number | undefined; top?: number | undefined; bottom?: number | undefined; }	-	-
behavior	ScrollBehavior	-	-
eventListenerOptions	AddEventListenerOptions	-	-
window	WindowSource	-	-

Returns

UseScrollReturn

Name	Type	Description
x$	ObservablePrimitive<number>	-
y$	ObservablePrimitive<number>	-
isScrolling$	ObservableBoolean<boolean>	-
arrivedState$	Observable<ArrivedState>	-
directions$	Observable<ScrollDirections>	-
measure	() => void	-

Source

View on GitHub