react-resize-detector

To ensure high performance when using the library, follow these best practices:

1. Limit dimension tracking: Use handleWidth: false or handleHeight: false if you only need to monitor one dimension.
2. Skip initial mount: Use skipOnMount: true if you do not need the initial measurements immediately upon mounting.
3. Rate limit updates: Use refreshMode: 'debounce' or 'throttle' with a refreshRate for expensive resize handlers (e.g., redrawing charts).
4. Use disableRerender: If you only need to perform side effects (like updating external state or logging) without triggering a React component re-render, set disableRerender: true and use the onResize callback.
5. Specify box model: Use observerOptions: { box: 'border-box' } for more consistent and accurate measurements.

You can install the library using npm, yarn, or pnpm.

npm install react-resize-detector
# OR
yarn add react-resize-detector
# OR
pnpm add react-resize-detector

You can observe an element by passing an existing targetRef to the hook.

Warning: This approach is not advised as dynamically mounting and unmounting the observed element could lead to unexpected behavior.

import { useRef } from 'react';
import { useResizeDetector } from 'react-resize-detector';

const CustomComponent = () => {
  const targetRef = useRef<HTMLDivElement>(null);
  const { width, height } = useResizeDetector({ targetRef });
  return <div ref={targetRef}>{`${width}x${height}`}</div>;
};

The useResizeDetector hook is the primary way to detect element size changes. It returns an object containing the current width, height, and a ref that you must attach to the element you want to observe.

import { useResizeDetector } from 'react-resize-detector';

const CustomComponent = () => {
  const { width, height, ref } = useResizeDetector<HTMLDivElement>();
  return <div ref={ref}>{`${width}x${height}`}</div>;
};

You can provide an onResize callback to handle resize events manually. The callback receives a ResizePayload which contains the new dimensions. If the element unmounts, the dimensions will be null.

import { useCallback } from 'react';
import { useResizeDetector, OnResizeCallback } from 'react-resize-detector';

const CustomComponent = () => {
  const onResize: OnResizeCallback = useCallback((payload) => {
    if (payload.width !== null && payload.height !== null) {
      console.log('Dimensions:', payload.width, payload.height);
    } else {
      console.log('Element unmounted');
    }
  }, []);

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

  return <div ref={ref}>{`${width}x${height}`}</div>;
};

The following types are exported for use in TypeScript applications to ensure type safety when working with the hook's return values, props, and callbacks:

• UseResizeDetectorReturn: The shape of the object returned by the useResizeDetector hook.
• useResizeDetectorProps: The configuration options available for the hook.
• OnResizeCallback: The type for the function called when a resize event occurs.
• ResizePayload: The data passed to the resize callback.
• RefreshModeType: Defines how the detector should refresh.
• RefreshOptionsType: Configuration for the refresh mechanism.
• Dimensions: The structure of the width and height data.

export type {
  UseResizeDetectorReturn,
  useResizeDetectorProps,
  OnResizeCallback,
  ResizePayload,
  RefreshModeType,
  RefreshOptionsType,
  Dimensions,
}

The onResize callback receives a ResizePayload object. This object's structure depends on whether the observed element is currently mounted:

• When mounted: { width: number; height: number; entry: ResizeObserverEntry }
• When unmounted: { width: null; height: null; entry: null }

export type ResizePayload =
  | { width: number; height: number; entry: ResizeObserverEntry }
  | { width: null; height: null; entry: null };

The useResizeDetector hook returns an object of type UseResizeDetectorReturn<T>, which contains the current dimensions and a ref callback to attach to the target element.

• width: The current width of the element (number or undefined).
• height: The current height of the element (number or undefined).
• ref: A callback ref (OnRefChangeType) used to connect the hook to a DOM element.

export interface UseResizeDetectorReturn<T> extends Dimensions {
  ref: OnRefChangeType<T>;
}

export type Dimensions = {
  height?: number;
  width?: number;
};