@react-hook/window-size

React hooks for updating components when the size of the `window` changes.

Usage no npm install needed!

<script type="module">
  import reactHookWindowSize from 'https://cdn.skypack.dev/@react-hook/window-size';
</script>

README


useWindowSize()

Bundlephobia Types Build status NPM Version MIT License

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