@react-hook/window-size

What is @react-hook/window-size?

@react-hook/window-size is a React hook that allows you to easily get the current window size and respond to window resize events. It provides a simple API to access the width and height of the window, making it useful for responsive design and dynamic layout adjustments.

What are @react-hook/window-size's main functionalities?

Get Window Size

This feature allows you to get the current width and height of the window. The `useWindowSize` hook returns an array with the width and height, which you can use to render responsive components.

import { useWindowSize } from '@react-hook/window-size';

function MyComponent() {
  const [width, height] = useWindowSize();

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

Custom Throttle

This feature allows you to throttle the resize event updates. By passing a number to `useWindowSize`, you can control how often the window size is updated, which can improve performance by reducing the frequency of re-renders.

import { useWindowSize } from '@react-hook/window-size';

function MyComponent() {
  const [width, height] = useWindowSize(250); // Throttle updates every 250ms

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

Other packages similar to @react-hook/window-size

react-use

react-use is a collection of essential React hooks, including a `useWindowSize` hook. It provides similar functionality to @react-hook/window-size but also includes a wide variety of other hooks for different use cases, making it a more comprehensive solution for managing state and side effects in React applications.

react-responsive

react-responsive is a package that allows you to create media query components in React. While it doesn't provide a direct hook for window size, it offers a more declarative approach to handling responsive design by allowing you to define breakpoints and render different components based on the current viewport size.

use-resize-observer

use-resize-observer is a React hook that uses the ResizeObserver API to track the size of a DOM element. While it is more focused on element size rather than window size, it can be used to achieve similar results by observing the document's root element. It provides more granular control over resizing behavior compared to @react-hook/window-size.

README

---

useWindowSize()

npm i @react-hook/window-size

---

React hooks for updating components when the size or orientation of the window changes. These hooks come in two forms: debounced using useDebounce() and throttled using useThrottle().

Quick Start

Check out the example on CodeSandbox

//
// Debounced values
import {
  useWindowSize,
  useWindowWidth,
  useWindowHeight,
} from '@react-hook/window-size'

const Component = (props) => {
  const [width, height] = useWindowSize()
  const onlyWidth = useWindowWidth()
  const onlyHeight = useWindowHeight()
}

//
// Throttled values
import {
  useWindowSize,
  useWindowWidth,
  useWindowHeight,
} from '@react-hook/window-size/throttled'

const Component = (props) => {
  const [width, height] = useWindowSize()
  const onlyWidth = useWindowWidth()
  const onlyHeight = useWindowHeight()
}

API

useWindowSize(options?): [number, number]

A hook that returns the current width and height of the window. This hook is debounced, meaning it will wait (100ms by default) for the resize events to stop firing before it actually updates its state with the new width and height.

Options

	Type	Required?	Description
options	DebouncedWindowSizeOptions	No	Options for configuring the hook. See DebouncedWindowSizeOptions below.

DebouncedWindowSizeOptions

Key	Type	Default	Description
wait	number	100	The amount of time in ms you want to wait after the latest resize event before updating the size of the window in state.
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to debouncing any additional events.
initialWidth	number	0	The initial width to use when there is no window object, e.g. SSR
initialHeight	number	0	The initial height to use when there is no window object, e.g. SSR

Returns [width: number, height: number]

	Type	Description
width	number	The current clientWidth of the window
height	number	The current clientHeight of the window

---

useWindowWidth(options?): number

A hook that returns the current width of the window. This hook is debounced, meaning it will wait (100ms by default) for the resize events to stop firing before it actually updates its state with the new width.

Options

	Type	Required?	Description
options	DebouncedWindowSizeOptions	No	Options for configuring the hook. See DebouncedWindowSizeOptions below.

DebouncedWindowSizeOptions

Key	Type	Default	Description
wait	number	100	The amount of time in ms you want to wait after the latest resize event before updating the size of the window in state.
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to debouncing any additional events.
initialWidth	number	0	The initial width to use when there is no window object, e.g. SSR

Returns width: number

	Type	Description
width	number	The current clientWidth of the window

---

useWindowHeight(options?): number

A hook that returns the current height of the window. This hook is debounced, meaning it will wait (100ms by default) for the resize events to stop firing before it actually updates its state with the new height.

Options

	Type	Required?	Description
options	DebouncedWindowSizeOptions	No	Options for configuring the hook. See DebouncedWindowSizeOptions below.

DebouncedWindowSizeOptions

Key	Type	Default	Description
wait	number	100	The amount of time in ms you want to wait after the latest resize event before updating the size of the window in state.
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to debouncing any additional events.
initialHeight	number	0	The initial height to use when there is no window object, e.g. SSR

Returns height: number

	Type	Description
height	number	The current clientHeight of the window

---

Throttled API

To use these throttled hooks instead of debounced hooks, import with import {...} from '@react-hook/window-size/throttled

useWindowSize(options?): [number, number]

A hook that returns the current width and height of the window. This hook is throttled, meaning it will only update its state at most 30fps (by default, configuration below) with the new width and height of the window. It will always update at the trailing edge, so you don't have to worry about not having the correct width or height after the window is finished resizing. It will also update at the leading edge if configured to do so.

Options

	Type	Required?	Description
options	ThrottledWindowSizeOptions	No	Options for configuring the hook. See ThrottledWindowSizeOptions below.

ThrottledWindowSizeOptions

Key	Type	Default	Description
fps	number	30	The rate in frames per second at which the size of the window is updated
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to throttling any additional events.
initialWidth	number	0	The initial width to use when there is no window object, e.g. SSR
initialHeight	number	0	The initial height to use when there is no window object, e.g. SSR

Returns [width: number, height: number]

	Type	Description
width	number	The current clientWidth of the window
height	number	The current clientHeight of the window

---

useWindowWidth(options?): number

A hook that returns the current width of the window. This hook is throttled, meaning it will only update its state at most 30fps (by default, configuration below) with the new width of the window. It will always update at the trailing edge, so you don't have to worry about not having the correct width after the window is finished resizing. It will also update at the leading edge if configured to do so.

Options

	Type	Required?	Description
options	ThrottledWindowSizeOptions	No	Options for configuring the hook. See ThrottledWindowSizeOptions below.

ThrottledWindowSizeOptions

Key	Type	Default	Description
fps	number	30	The rate in frames per second at which the size of the window is updated
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to throttling any additional events.
initialWidth	number	0	The initial width to use when there is no window object, e.g. SSR

Returns width: number

	Type	Description
width	number	The current clientWidth of the window

---

useWindowHeight(options?): number

A hook that returns the current height of the window. This hook is throttled, meaning it will only update its state at most 30fps (by default, configuration below) with the new height of the window. It will always update at the trailing edge, so you don't have to worry about not having the correct height after the window is finished resizing. It will also update at the leading edge if configured to do so.

Options

	Type	Required?	Description
options	ThrottledWindowSizeOptions	No	Options for configuring the hook. See ThrottledWindowSizeOptions below.

ThrottledWindowSizeOptions

Key	Type	Default	Description
fps	number	30	The rate in frames per second at which the size of the window is updated
leading	boolean	false	When true, updates the size of the window on the leading edge (right away) in addition to throttling any additional events.
initialHeight	number	0	The initial height to use when there is no window object, e.g. SSR

Returns height: number

	Type	Description
height	number	The current clientHeight of the window

LICENSE

MIT