gem-hunter

Handle element resizes like it's 2025!

Live demo

Should you use this library?

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

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)

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

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

Disable Re-renders

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

const NonRerenderingComponent = () => {
  const { ref } = useResizeDetector({
    // Disable re-renders triggered by the hook
    disableRerender: true,
    // Handle resize events through callback only
    onResize: ({ width, height }) => {
      // Update external state or perform side effects
      // without causing component re-renders
      console.log('Resized to:', width, height);
    },
  });

  return <div ref={ref}>This component won't re-render on resize</div>;
};

Browser Support

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

License

❤️ Support