Repository files navigation

A React hook that allows you to use a ResizeObserver to measure an element's size.

• Written inTypeScript.
• Tiny:648B (minified, gzipped) Monitored bysize-limit.
• Exposes anonResize callback if you need more control.
• boxoption.
• Works withSSR.
• Works withCSS-in-JS.
• Supports custom refs in case youhad one already.
• Uses RefCallback by default To address delayed mounts and changing ref elements.
• Ships a polyfilled version
• Handles many edge cases you might not even think of.(See this documentation and the test cases.)
• Easy to compose (Throttle / Debounce,Breakpoints)
• Tested in real browsers (Currently latest Chrome, Firefox, Edge, Safari, Opera, IE 11, iOS and Android, sponsored by BrowserStack)

CodeSandbox Demo

yarn add use-resize-observer --dev# ornpm install use-resize-observer --save-dev

Note that the default builds are not polyfilled! For instructions and alternatives,see theTranspilation / Polyfilling section.

importReactfrom"react";importuseResizeObserverfrom"use-resize-observer";constApp=()=>{const{ ref, width=1, height=1}=useResizeObserver<HTMLDivElement>();return(<divref={ref}>      Size:{width}x{height}</div>);};

To observe a different box size other than content box, pass in thebox option, like so:

const{ ref, width, height}=useResizeObserver<HTMLDivElement>({box:"border-box",});

Note that if the browser does not support the given box type, then the hook won't report any sizes either.

Note that box options are experimental, and as such are not supported by all browsers that implemented ResizeObservers. (Seehere.)

content-box (default)

Safe to use by all browsers that implemented ResizeObservers. The hook internally will fall back tocontentRect fromthe old spec in casecontentBoxSize is not available.

border-box

Supported well for the most part by evergreen browsers. If you need to support older versions of these browsers however,then you may want to feature-detect for support, and optionally include a polyfill instead of the native implementation.

device-pixel-content-box

Surma has avery good article on how this allows us to do pixel perfectrendering. At the time of writing, however this has very limited support.The advices on feature detection forborder-box apply here too.

By default this hook passes the measured values throughMath.round(), to avoid re-rendering on every subpixel changes.

If this is not what you want, then you can provide your own function:

Rounding Down Reported Values

const{ ref, width, height}=useResizeObserver<HTMLDivElement>({round:Math.floor,});

Skipping Rounding

importReactfrom"react";importuseResizeObserverfrom"use-resize-observer";// Outside the hook to ensure this instance does not change unnecessarily.constnoop=(n)=>n;constApp=()=>{const{    ref,    width=1,    height=1,}=useResizeObserver<HTMLDivElement>({round:noop});return(<divref={ref}>      Size:{width}x{height}</div>);};

Note that the round option is sensitive to the function reference, so make sure you either useuseCallbackor declare your rounding function outside of the hook's function scope, if it does not rely on any hook state.(As shown above.)

Note that "ref" in the above examples is aRefCallback, not aRefObject, meaning you won't beable to access "ref.current" if you need the element itself.

To get the raw element, either you use your own RefObject (see later in this doc),or you can merge the returned ref with one of your own:

importReact,{useCallback,useEffect,useRef}from"react";importuseResizeObserverfrom"use-resize-observer";importmergeRefsfrom"react-merge-refs";constApp=()=>{const{ ref, width=1, height=1}=useResizeObserver<HTMLDivElement>();constmergedCallbackRef=mergeRefs([ref,(element:HTMLDivElement)=>{// Do whatever you want with the `element`.},]);return(<divref={mergedCallbackRef}>      Size:{width}x{height}</div>);};

You can pass in your own ref instead of using the one provided.This can be useful if you already have a ref you want to measure.

constref=useRef<HTMLDivElement>(null);const{ width, height}=useResizeObserver<HTMLDivElement>({ ref});

You can even reuse the same hook instance to measure different elements:

CodeSandbox Demo

There might be situations where you have an element already that you need to measure.ref now accepts elements as well, not just refs, which means that you can do this:

const{ width, height}=useResizeObserver<HTMLDivElement>({ref:divElement,});

The hook reacts to ref changes, as it resolves it to an element to observe.This means that you can freely change the customref option from one ref toanother and back, and the hook will start observing whatever is set in its options.

In certain cases you might want to delay creating a ResizeObserver instance.

You might provide a library, that only optionally provides observation featuresbased on props, which means that while you have the hook within your component,you might not want to actually initialise it.

Another example is that you might want to entirely opt out of initialising, whenyou run some tests, where the environment does not provide theResizeObserver.

(See discussions)

You can do one of the following depending on your needs:

• Use the defaultref RefCallback, or provide a custom ref conditionally,only when needed. The hook will not create a ResizeObserver instance up untilthere's something there to actually observe.
• Patch the test environment, and make a polyfill available as the ResizeObserver.(This assumes you don't already use the polyfilled version, which would switchto the polyfill when no native implementation was available.)

By the default the hook will trigger a re-render on all changes to the targetelement's width and / or height.

You can opt out of this behaviour, by providing anonResize callback function,which'll simply receive the width and height of the element when it changes, sothat you can decide what to do with it:

importReactfrom"react";importuseResizeObserverfrom"use-resize-observer";constApp=()=>{// width / height will not be returned here when the onResize callback is presentconst{ ref}=useResizeObserver<HTMLDivElement>({onResize:({ width, height})=>{// do something here.},});return<divref={ref}/>;};

This callback also makes it possible to implement your own hooks that report onlywhat you need, for example:

• Reporting only width or height
• Throttle / debounce
• Wrap inrequestAnimationFrame

As this hook intends to remain low-level, it is encouraged to build on top of it via hook composition, if additional features are required.

You might want to receive values less frequently than changes actually occur.

CodeSandbox Demo

Another popular concept are breakpoints. Here is an example for a simple hook accomplishing that.

CodeSandbox Demo

On initial mount the ResizeObserver will take a little time to report on theactual size.

Until the hook receives the first measurement, it returnsundefined for widthand height by default.

You can override this behaviour, which could be useful for SSR as well.

const{ ref, width=100, height=50}=useResizeObserver<HTMLDivElement>();

Here "width" and "height" will be 100 and 50 respectively, until theResizeObserver kicks in and reports the actual size.

If you only want real measurements (only values from the ResizeObserver withoutany default values), then you can just leave defaults off:

const{ ref, width, height}=useResizeObserver<HTMLDivElement>();

Here "width" and "height" will be undefined until the ResizeObserver takes itsfirst measurement.

It's possible to apply styles conditionally based on the width / height of anelement using a CSS-in-JS solution, which is the basic idea behindcontainer/element queries:

CodeSandbox Demo

By default the library provides transpiled ES5 modules in CJS / ESM module formats.

Polyfilling is recommended to be done in the host app, and not within importedlibraries, as that way consumers have control over the exact polyfills being used.

That said, there's apolyfilledCJS module that can be used for convenience:

importuseResizeObserverfrom"use-resize-observer/polyfilled";

Note that using the above will use the polyfill,even if the native ResizeObserver is available.

To use the polyfill as a fallback only when the native RO is unavailable, you can polyfill yourself instead,either in your app's entry file, or you could create a localuseResizeObserver module, like so:

// useResizeObserver.tsimport{ResizeObserver}from"@juggle/resize-observer";importuseResizeObserverfrom"use-resize-observer";if(!window.ResizeObserver){window.ResizeObserver=ResizeObserver;}exportdefaultuseResizeObserver;

The same technique can also be used to provide any of your preferred ResizeObserver polyfills out there.

• @zeecoder/container-query
• @zeecoder/react-resize-observer

MIT