Sensors

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

Hook
Scope

import { 
const useWindowScroll: (options?: DeepMaybeObservable<UseWindowScrollOptions>) => UseWindowScrollReturn
useWindowScroll } from "@usels/web";

function 
function Component(): JSX.Element
Component() {
  const { 
const x$: any
x$, 
const y$: any
y$, 
const arrivedState$: any
arrivedState$ } = 
function useWindowScroll(options?: DeepMaybeObservable<UseWindowScrollOptions>): UseWindowScrollReturn
useWindowScroll();

  return (
    <
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
      scrollX: {
const x$: any
x$.
any
get()}, scrollY: {
const y$: any
y$.
any
get()}
      {
const arrivedState$: any
arrivedState$.
any
bottom.
any
get() && " — reached bottom"}
    </
JSX.IntrinsicElements.p: DetailedHTMLProps<HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>
p>
  );
}

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

function Component() {
  "use scope"
  const { x$, y$, arrivedState$ } = createWindowScroll();

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

Back-to-top button

// @noErrors
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 "@usels/core";

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

Parameters

Parameter	Type	Description
`options`	`UseScrollOptions` (optional)	-

UseWindowScrollOptions

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