Handle element resizes like it's 2025!

Live demo

Modern browsers now have native support for detecting element size changes through ResizeObservers. This library utilizes ResizeObservers to facilitate managing element size changes in React applications.

🐥 Tiny ~2kb

🐼 Written in TypeScript

🐠 Used by 170k repositories

🦄 Produces 100 million downloads annually

No window.resize listeners! No timeouts!

Should you use this library?

Consider CSS Container Queries first! They now work in all major browsers and might solve your use case with pure CSS.

CSS Container Queries Example

<div class="post">
  <div class="card">
    <h2>Card title</h2>
    <p>Card content</p>
  </div>
</div>

.post {
  container-type: inline-size;
}

/* Default heading styles for the card title */
.card h2 {
  font-size: 1em;
}

/* If the container is larger than 700px */
@container (min-width: 700px) {
  .card h2 {
    font-size: 2em;
  }
}

Use this library when you need:

• JavaScript-based resize logic with full TypeScript support
• Complex calculations based on dimensions
• Integration with React state/effects
• Programmatic control over resize behavior

Installation

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

Quick Start

Basic Usage

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

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

With Resize Callback

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

With External Ref (Advanced)

It's not advised to use this approach, 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>;
};

API Reference

Hook Signature

useResizeDetector<T extends HTMLElement = HTMLElement>(
  props?: useResizeDetectorProps<T>
): UseResizeDetectorReturn<T>

Props

Prop	Type	Description	Default
onResize	(payload: ResizePayload) => void	Callback invoked with resize information	undefined
handleWidth	boolean	Trigger updates on width changes	true
handleHeight	boolean	Trigger updates on height changes	true
skipOnMount	boolean	Skip the first resize event when component mounts	false
refreshMode	'throttle' | 'debounce'	Rate limiting strategy. See lodash docs	undefined
refreshRate	number	Delay in milliseconds for rate limiting	1000
refreshOptions	{ leading?: boolean; trailing?: boolean }	Additional options for throttle/debounce	undefined
observerOptions	ResizeObserverOptions	Options passed to resizeObserver.observe	undefined
targetRef	MutableRefObject<T | null>	External ref to observe (use with caution)	undefined

Advanced Examples

Responsive Component

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

const ResponsiveCard = () => {
  const { width, ref } = useResizeDetector();

  const cardStyle = {
    padding: width > 600 ? '2rem' : '1rem',
    fontSize: width > 400 ? '1.2em' : '1em',
    flexDirection: width > 500 ? 'row' : 'column',
  };

  return (
    <div ref={ref} style={cardStyle}>
      <h2>Responsive Card</h2>
      <p>Width: {width}px</p>
    </div>
  );
};

Chart Resizing

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

const Chart = () => {
  const chartRef = useRef(null);
  const { width, height, ref } = useResizeDetector({
    refreshMode: 'debounce',
    refreshRate: 100,
  });

  useEffect(() => {
    if (width && height && chartRef.current) {
      // Redraw chart with new dimensions
      redrawChart(chartRef.current, width, height);
    }
  }, [width, height]);

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

Performance Optimization

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

const OptimizedComponent = () => {
  const { width, height, ref } = useResizeDetector({
    // Only track width changes
    handleHeight: false,
    // Debounce rapid changes
    refreshMode: 'debounce',
    refreshRate: 150,
    // Skip initial mount calculation
    skipOnMount: true,
    // Use border-box for more accurate measurements
    observerOptions: { box: 'border-box' },
  });

  return <div ref={ref}>Optimized: {width}px wide</div>;
};

Browser Support

• ✅ Chrome 64+
• ✅ Firefox 69+
• ✅ Safari 13.1+
• ✅ Edge 79+

For older browsers, consider using a ResizeObserver polyfill.

Testing

const { ResizeObserver } = window;

beforeEach(() => {
  delete window.ResizeObserver;
  // Mock ResizeObserver for tests
  window.ResizeObserver = jest.fn().mockImplementation(() => ({
    observe: jest.fn(),
    unobserve: jest.fn(),
    disconnect: jest.fn(),
  }));
});

afterEach(() => {
  window.ResizeObserver = ResizeObserver;
  jest.restoreAllMocks();
});

Performance Tips

1. Use handleWidth/handleHeight: false if you only need one dimension
2. Enable skipOnMount: true if you don't need initial measurements
3. Use debounce or throttle for expensive resize handlers
4. Specify observerOptions.box for consistent measurements

License

MIT

❤️ Support

Show us some love and STAR ⭐ the project if you find it useful