react-window-size-listener

A minimalistic, modern React hook for listening to window resize events with built-in debouncing.

Features

• Minimalistic: Tiny footprint, no external dependencies.
• Modern: Written in TypeScript, built as a React Hook.
• Performant: Built-in debouncing and passive event listeners to prevent excessive re-renders and scroll jank.
• SSR Safe: Checks for window existence, safe to use in Next.js/Gatsby/Remix.

Installation

npm install react-window-size-listener
# or
yarn add react-window-size-listener
# or
pnpm add react-window-size-listener

Usage

useWindowSize

This hook returns an object containing the current width and height of the window.

import React from 'react';
import { useWindowSize } from 'react-window-size-listener';

function App() {
  const { width, height } = useWindowSize();

  return (
    <div>
      <h1>Window Size</h1>
      <p>Width: {width}px</p>
      <p>Height: {height}px</p>
    </div>
  );
}

SSR / Next.js Usage

When using with Next.js App Router, ensure you use the "use client" directive since this hook relies on browser APIs.

"use client";

import { useWindowSize } from 'react-window-size-listener';

export default function ClientComponent() {
  const { width } = useWindowSize();
  return <div>Window width: {width}</div>;
}

Advanced Example: useBreakpoint helper

You can easily compose this hook to create a breakpoint helper.

import { useWindowSize } from 'react-window-size-listener';

const useBreakpoint = () => {
  const { width } = useWindowSize();

  if (width < 640) return 'sm';
  if (width < 768) return 'md';
  if (width < 1024) return 'lg';
  return 'xl';
};

Configuration

You can customize the debounce time by passing an options object. The default is 100ms.

// Wait 500ms after the last resize event before updating state
const { width, height } = useWindowSize({ debounceTime: 500 });

useViewportSize

Returns the visual viewport size using the Visual Viewport API. This accounts for pinch-zoom, on-screen keyboards, and browser chrome on mobile devices. Falls back to window dimensions if the API is not available.

import { useViewportSize } from 'react-window-size-listener';

function App() {
  const { width, height } = useViewportSize();

  return (
    <div>
      <p>Viewport: {width} x {height}</p>
    </div>
  );
}

API

useWindowSize(options?)

Tracks window.innerWidth and window.innerHeight.

useViewportSize(options?)

Tracks the visual viewport dimensions (with fallback to window dimensions).

Property	Type	Default	Description
options.debounceTime	number	100	Delay in ms before updating state after resize
Returns	WindowSize		Object { width: number, height: number }

TypeScript Types

The library exports the following types for your convenience:

import type { WindowSize, UseWindowSizeOptions } from 'react-window-size-listener';

Migration from v1

Version 2.0.0 is a complete rewrite. The old Class Component WindowSizeListener and HOC withWindowSizeListener have been removed in favor of the useWindowSize hook.

Old way (v1):

<WindowSizeListener onResize={windowSize => console.log(windowSize)} />

New way (v2.0+):

const { width, height } = useWindowSize();
useEffect(() => {
  console.log({ width, height });
}, [width, height]);

License

MIT