useWindowScroll

Tracks the window scroll position, direction, arrived state, and scrolling status as reactive Observable values. A convenience wrapper around useScroll(window).

Demo

x: 0y: 0idle

topbottomleftright

Scroll the page to see the values update in real time.

Usage

Basic

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

function Component() {
  const { x, y, arrivedState } = useWindowScroll();

  return (
    <p>
      scrollX: {x.get()}, scrollY: {y.get()}
      {arrivedState.bottom.get() && " — reached bottom"}
    </p>
  );
}

Back-to-top button

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

function BackToTop() {
  const { arrivedState } = useWindowScroll();

  return !arrivedState.top.get() ? (
    <button onClick={() => window.scrollTo({ top: 0, behavior: "smooth" })}>↑ Back to top</button>
  ) : null;
}

Scroll direction indicator

const { directions } = useWindowScroll();
// directions.bottom.get() → true while scrolling down
// directions.top.get()    → true while scrolling up

Infinite scroll trigger

import { useObserveEffect } from "@legendapp/state/react";

const { arrivedState } = useWindowScroll({ offset: { bottom: 200 } });

useObserveEffect(arrivedState.bottom, (e) => {
  if (e.value) fetchNextPage();
});

isScrolling + onStop

const { isScrolling } = useWindowScroll({
  idle: 300,
  onStop: () => saveScrollPosition(),
});

Throttled updates

const { y } = useWindowScroll({ throttle: 100 });

Notes

SSR-safe. When window is not available (SSR), useWindowScroll passes null to useScroll, so all observables hold initial values (x: 0, y: 0, isScrolling: false) and no event listener is registered.

See useScroll for the full API reference including all options.

Type Declarations

export type { UseScrollOptions, UseScrollReturn };
export declare function useWindowScroll(options?: UseScrollOptions): UseScrollReturn;

Source

View on GitHub

Contributors

• tigerwest

Changelog

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