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

Basic — HTMLElement

import { useScroll, 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>
  );
}

Window scroll

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

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

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

Scroll direction

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

function Component() {
  const el$ = useRef$<HTMLDivElement>();
  const { directions$ } = useScroll(el$);

  // directions$.bottom.get() → true while scrolling down
  // directions$.top.get()    → true while scrolling up
}

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();

Null / SSR-safe target

Passing null is safe — all observables stay at their initial values and no event listener is registered.

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

const target = typeof window !== "undefined" ? document : null;
const { y$ } = useScroll(target);

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 (useObserve, etc.) 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.

Type Declarations

export interface UseScrollOptions {
    throttle?: number;
    idle?: number;
    onScroll?: (e: Event) => void;
    onStop?: () => void;
    onError?: (error: unknown) => void;
    offset?: {
        left?: number;
        right?: number;
        top?: number;
        bottom?: number;
    };
    behavior?: ScrollBehavior;
    eventListenerOptions?: MaybeObservable<AddEventListenerOptions>;
}
export interface ArrivedState {
    left: boolean;
    right: boolean;
    top: boolean;
    bottom: boolean;
}
export interface ScrollDirections {
    left: boolean;
    right: boolean;
    top: boolean;
    bottom: boolean;
}
export interface UseScrollReturn {
    x$: Observable<number>;
    y$: Observable<number>;
    isScrolling$: Observable<boolean>;
    arrivedState$: Observable<ArrivedState>;
    directions$: Observable<ScrollDirections>;
    measure: () => void;
}
export declare function useScroll(element: MaybeElement, options?: UseScrollOptions): UseScrollReturn;

Source

View on GitHub

Contributors

• tigerwest

Changelog

• a7392ab 2026-03-06 - feat(core,browser): add sync strategy hooks (tigerwest)