use-resize-observer

What is use-resize-observer?

The use-resize-observer package provides a React hook that allows you to monitor an element for size changes. It is useful for responsive design and element-specific adjustments based on width and height. It leverages the ResizeObserver API to offer a simple and efficient way to react to size changes in components.

What are use-resize-observer's main functionalities?

Basic usage for monitoring size changes

This code demonstrates how to use the use-resize-observer hook to monitor the size of a component. By destructuring `ref`, `width`, and `height` from the hook, you can easily track the dimensions of the element that the `ref` is attached to.

import useResizeObserver from 'use-resize-observer';

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

  return (
    <div ref={ref}>
      The width is {width} and the height is {height}.
    </div>
  );
};

Using with a callback

This example shows how to use the hook with a callback function. The `onResize` option allows you to provide a function that will be called whenever the observed element's size changes, receiving the new `width` and `height` as parameters.

import useResizeObserver from 'use-resize-observer';

const MyComponent = () => {
  const { ref } = useResizeObserver({
    onResize: ({ width, height }) => {
      console.log(`New size: ${width}x${height}`);
    }
  });

  return <div ref={ref}>Resize me and check the console!</div>;
};

Other packages similar to use-resize-observer

react-resize-detector

react-resize-detector is another package that provides components and hooks to listen to resize events. Compared to use-resize-observer, it offers more customization options, such as the ability to choose between a hook or a higher-order component for detecting resize events. However, use-resize-observer might be simpler to use for straightforward use cases.

resize-observer-polyfill

resize-observer-polyfill is not a React-specific package but a polyfill for the ResizeObserver API. It can be used in conjunction with React but requires manual setup and teardown of the observer. use-resize-observer abstracts this setup, offering a more integrated React hook approach.

README

use-resize-observer

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

Highlights

• Written in TypeScript.
• Tiny: 500B (minified, gzipped) Monitored by size-limit.
• Exposes an onResize callback if you need more control.
• Works with SSR.
• Works with CSS-in-JS.
• Supports custom refs in case you had 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.)
• Throttle / Debounce
• Tested in real browsers (Currently latest Chrome, Safari, Firefox and IE 11, sponsored by BrowserStack)

In Action

CodeSandbox Demo

Install

yarn add use-resize-observer --dev
# or
npm install use-resize-observer --save-dev

Basic Usage

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

import React from "react";
import useResizeObserver from "use-resize-observer";

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

  return (
    <div ref={ref}>
      Size: {width}x{height}
    </div>
  );
};

Note that "ref" here is a RefCallback, not a RefObject, meaning you won't be able 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 hook in the returned ref callback, like so:

Getting the raw element from the default RefCallback

import React, { useCallback, useEffect, useRef } from "react";
import useResizeObserver from "use-resize-observer";

const useMergedCallbackRef = (...callbacks: Function[]) => {
  // Storing callbacks in a ref, so that we don't need to memoise them in
  // renders when using this hook.
  const callbacksRegistry = useRef<Function[]>(callbacks);

  useEffect(() => {
    callbacksRegistry.current = callbacks;
  }, [...callbacks]);

  return useCallback((element) => {
    callbacksRegistry.current.forEach((callback) => callback(element));
  }, []);
};

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

  const mergedCallbackRef = useMergedCallbackRef(
    ref,
    (element: HTMLDivElement) => {
      // Do whatever you want with the `element`.
    }
  );

  return (
    <div ref={mergedCallbackRef}>
      Size: {width}x{height}
    </div>
  );
};

Passing in Your Own ref

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.

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

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

CodeSandbox Demo

Measuring a raw element

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,
});

Using a single hook to measure multiple refs

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

Opting Out of (or Delaying) ResizeObserver instantiation

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

You might provide a library, that only optionally provides observation features based 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, when you run some tests, where the environment does not provide the ResizeObserver.

(See discussions)

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

• Use the default ref RefCallback, or provide a custom ref conditionally, only when needed. The hook will not create a ResizeObserver instance up until there'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 switch to the polyfill when no native implementation was available.)

The "onResize" callback

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

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

import React from "react";
import useResizeObserver from "use-resize-observer";

const App = () => {
  // width / height will not be returned here when the onResize callback is present
  const { ref } = useResizeObserver<HTMLDivElement>({
    onResize: ({ width, height }) => {
      // do something here.
    },
  });

  return <div ref={ref} />;
};

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

• Reporting only width or height
• Throttle / debounce
• Wrap in requestAnimationFrame

Throttle / Debounce

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

While this hook does not come with its own implementation of throttling / debouncing, you can use the onResize callback to implement your own version:

CodeSandbox Demo

Defaults (SSR)

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

Until the hook receives the first measurement, it returns undefined for width and 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 the ResizeObserver kicks in and reports the actual size.

Without Defaults

If you only want real measurements (only values from the ResizeObserver without any 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 its first measurement.

Container/Element Query with CSS-in-JS

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

CodeSandbox Demo

Transpilation / Polyfilling

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 imported libraries, as that way consumers have control over the exact polyfills being used.

That said, there's a polyfilled CJS module that can be used for convenience (Not affecting globals):

import useResizeObserver from "use-resize-observer/polyfilled";

Related

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

License

MIT

Changelog

7.0.0 (2020-11-11)

Bug Fixes

• Only instantiating a ResizeObserver instance if there's actually something to observe. This for example means that if you pass in null or undefined as the ref, or if neither the default ref or RefCallback returned from the hook are in use, then no ResizeObserver instance will get created until there's an actual element to observe. Resolves: #42
• Fixed an error where in certain edge cases the hook tried to set state when its host component already unmounted.

Features

• The ref option now accepts raw elements as well.

BREAKING CHANGES

• The returned ref is now a RefCallback, not a ref object. Resolves: #43, #45
• The returned ref will always be the same RefCallback. Previously when a custom ref object was passed, it was returned as well from the hook as "ref".
• Compared to 6.2.0-alpha.1 There's no callbackRef return value anymore.

Misc

• Using package.json file attr instead of gitignore (c58f34e)
• Added Semantic Release (55f6368)
• Handling custom refs (through options), the default ref and the RefCallback has been greatly refactored internally (into the useResolvedElement hook), to handle more edge cases with the way refs are handled.
• Tests based on react testing library were refactored to make them much simpler and more approachable.
• Added contributing guidelines
• Added tests in real browsers with BrowserStack, so that we ensure the lib works all the way back to IE11.
• Switched to GitHub Actions from Travis, as builds started to freeze. (They've also announced a limit on OS projects.)