Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


0.2.7 • Public • Published


npm David npm GitHub issues NPM

a tiny React hook which allows you to track visible window viewport size in your components w/ an optional debounce for updates for optimal rendering.


npm install -D use-viewport-sizes


  • extremely lightweight and dependency-free -- 2.25kb before gzipping.
  • only one window.onresize handler used to subscribe to any changes in an unlimited number of components.
  • optional debounce to delay updates until user stops dragging their window for a moment; this can make expensive components with size-dependent calculations run much faster and your app feel smoother.
  • debouncing does not create new handlers or waste re-renders in your component; the results are also pooled from only one resize result.
  • supports SSR.


See it in Action

Interact with the example shown on CodeSandox @ https://codesandbox.io/s/j3vzpqxwww

Without Debouncing

registers dimension changes on every resize event immediately

import React from 'react'
import useViewportSizes from 'use-viewport-sizes'
function MyComponent (props) {
    const [vpWidth, vpHeight] = useViewportSizes();

With Debouncing

registers dimension changes only when a user stops dragging/resizing the window for a specified number of miliseconds; for expensive components such as data grids which may be too expensive to re-render during window resize dragging.

import React from 'react'
import useViewportSizes from 'use-viewport-sizes'
function MyExpensivelyRenderedComponent (props) {
    const [vpWidth, vpHeight] = useViewportSizes(1000); // 1s debounce

Server Side Rendering

While serverside rendering is supported, it requires an explicit update via useEffect since viewport does not actually exist on the server before rendering to client. The following has been tested with NextJS.

Sidenote that you will see a useLayoutEffect warning from React. This is perfectly normal as there is no viewport/context to paint to when pre-rendering in SSR and will not interfere with your app once served to the client

import React, { useLayoutEffect } from 'react'
import useViewportSizes from 'use-viewport-sizes'
function MySSRComponent (props) {
    const [vpWidth, vpHeight, updateVpSizes] = useViewportSizes()
    // below, we add one post-render update
    // in order to register the client's viewport sizes
    // after serving SSR content
    useEffect(()=> { updateVpSizes(); }, []);


If you have read the examples and have any issues which you know are glitches,or would like to request something changed, please feel free to post an issue on Github.

Otherwise, if this was useful and you'd like to show your support, no donations necessary, but please consider checking out the repo and giving a star.



npm i use-viewport-sizes

DownloadsWeekly Downloads






Unpacked Size

7.09 kB

Total Files


Last publish


  • avatar