All hooks / Viewport and media

useWindowScroll

169 B minified and brotliedSourceMarkdown✓ Works in all modern browsers

The window's scroll position in CSS pixels, updated on scroll.

Renders serverValue on the server and during hydration, then switches to the real position with no hydration mismatch. Re-renders on every scroll event that moves the page (not throttled).

Import

import { useWindowScroll } from '@vincent.ri/react-tils'
// or only this hook
import { useWindowScroll } from '@vincent.ri/react-tils/useWindowScroll'

Usage

const { y } = useWindowScroll()
return y > 400 ? <button onClick={() => window.scrollTo({ top: 0 })}>Top</button> : null

Live demo

When to use it

JS needs the scroll position, e.g. a "back to top" button after scrolling down, or parallax that depends on the exact offset.

When not to

You only need to know if an element is visible; use useInView, which does not re-render on every scroll. For a header that hides on scroll down, use useScrollDirection; for a reading progress bar, useScrollProgress; both re-render far less. For sticky elements, use CSS position: sticky. For scroll-linked animation, use CSS scroll-driven animations.

API

function useWindowScroll(serverValue?: WindowScroll): WindowScroll

Types

export type WindowScroll = {
  x: number;
  y: number;
};