React Ref Callback Pattern

Ref callbacks provide more control than useRef for dynamic scenarios. Here's how to use them.

Basic Ref Callback#

import { useCallback, useState } from 'react';

function MeasuredComponent() {
  const [height, setHeight] = useState(0);

  // Ref callback receives the DOM element
  const measuredRef = useCallback((node: HTMLDivElement | null) => {
    if (node !== null) {
      setHeight(node.getBoundingClientRect().height);
    }
  }, []);

  return (
    <div ref={measuredRef}>
      <p>This element is {height}px tall</p>
      <p>More content here...</p>
    </div>
  );
}

// Without useCallback (simpler but recreates on each render)
function SimpleRef() {
  const [width, setWidth] = useState(0);

  return (
    <div ref={(node) => {
      if (node) {
        setWidth(node.offsetWidth);
      }
    }}>
      Width: {width}px
    </div>
  );
}

Dynamic Element Lists#

import { useRef, useCallback } from 'react';

function DynamicList({ items }) {
  // Store refs for multiple elements
  const itemRefs = useRef<Map<string, HTMLLIElement>>(new Map());

  const setItemRef = useCallback((id: string) => {
    return (node: HTMLLIElement | null) => {
      if (node) {
        itemRefs.current.set(id, node);
      } else {
        itemRefs.current.delete(id);
      }
    };
  }, []);

  const scrollToItem = (id: string) => {
    const node = itemRefs.current.get(id);
    node?.scrollIntoView({ behavior: 'smooth' });
  };

  return (
    <ul>
      {items.map((item) => (
        <li key={item.id} ref={setItemRef(item.id)}>
          {item.name}
        </li>
      ))}
    </ul>
  );
}

Focus Management#

function AutoFocusInput() {
  const focusRef = useCallback((node: HTMLInputElement | null) => {
    if (node) {
      node.focus();
      node.select(); // Also select text
    }
  }, []);

  return <input ref={focusRef} defaultValue="Edit me" />;
}

// Focus first invalid field
function Form() {
  const firstErrorRef = useCallback((node: HTMLInputElement | null) => {
    if (node) {
      node.focus();
      node.scrollIntoView({ behavior: 'smooth', block: 'center' });
    }
  }, []);

  return (
    <form>
      <input name="name" />
      <input
        name="email"
        ref={hasError ? firstErrorRef : undefined}
      />
      <input name="phone" />
    </form>
  );
}

Intersection Observer#

import { useCallback, useState } from 'react';

function LazyImage({ src, alt }) {
  const [isVisible, setIsVisible] = useState(false);

  const imageRef = useCallback((node: HTMLImageElement | null) => {
    if (!node) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsVisible(true);
          observer.disconnect();
        }
      },
      { rootMargin: '100px' }
    );

    observer.observe(node);

    // Cleanup handled by disconnect on intersection
  }, []);

  return (
    <img
      ref={imageRef}
      src={isVisible ? src : '/placeholder.png'}
      alt={alt}
    />
  );
}

// With cleanup using useEffect
function ObservedElement({ onVisible }) {
  const [element, setElement] = useState<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!element) return;

    const observer = new IntersectionObserver(([entry]) => {
      if (entry.isIntersecting) {
        onVisible();
      }
    });

    observer.observe(element);

    return () => observer.disconnect();
  }, [element, onVisible]);

  return <div ref={setElement}>Observed content</div>;
}

ResizeObserver#

import { useCallback, useState, useEffect } from 'react';

function ResizableElement() {
  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
  const [element, setElement] = useState<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!element) return;

    const observer = new ResizeObserver((entries) => {
      const { width, height } = entries[0].contentRect;
      setDimensions({ width, height });
    });

    observer.observe(element);

    return () => observer.disconnect();
  }, [element]);

  return (
    <div ref={setElement} style={{ resize: 'both', overflow: 'auto' }}>
      <p>Width: {Math.round(dimensions.width)}px</p>
      <p>Height: {Math.round(dimensions.height)}px</p>
    </div>
  );
}

// Custom hook
function useResizeObserver<T extends HTMLElement>() {
  const [element, setElement] = useState<T | null>(null);
  const [size, setSize] = useState({ width: 0, height: 0 });

  useEffect(() => {
    if (!element) return;

    const observer = new ResizeObserver((entries) => {
      const { width, height } = entries[0].contentRect;
      setSize({ width, height });
    });

    observer.observe(element);
    return () => observer.disconnect();
  }, [element]);

  return [setElement, size] as const;
}

// Usage
function Component() {
  const [ref, { width, height }] = useResizeObserver<HTMLDivElement>();

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

Animation Trigger#

import { useCallback } from 'react';

function AnimatedElement() {
  const animateRef = useCallback((node: HTMLDivElement | null) => {
    if (!node) return;

    // Trigger CSS animation
    node.classList.add('animate-in');

    // Or use Web Animations API
    node.animate(
      [
        { opacity: 0, transform: 'translateY(20px)' },
        { opacity: 1, transform: 'translateY(0)' },
      ],
      {
        duration: 300,
        easing: 'ease-out',
        fill: 'forwards',
      }
    );
  }, []);

  return (
    <div ref={animateRef} className="card">
      Animated content
    </div>
  );
}

// Staggered animation for list
function AnimatedList({ items }) {
  const createAnimatedRef = useCallback((index: number) => {
    return (node: HTMLLIElement | null) => {
      if (!node) return;

      node.animate(
        [
          { opacity: 0, transform: 'translateX(-20px)' },
          { opacity: 1, transform: 'translateX(0)' },
        ],
        {
          duration: 300,
          delay: index * 50, // Stagger
          easing: 'ease-out',
          fill: 'forwards',
        }
      );
    };
  }, []);

  return (
    <ul>
      {items.map((item, index) => (
        <li key={item.id} ref={createAnimatedRef(index)}>
          {item.name}
        </li>
      ))}
    </ul>
  );
}

Third-Party Libraries#

import { useCallback, useEffect, useRef } from 'react';

function ChartComponent({ data }) {
  const chartInstance = useRef<Chart | null>(null);

  const chartRef = useCallback((canvas: HTMLCanvasElement | null) => {
    if (!canvas) {
      // Cleanup on unmount
      chartInstance.current?.destroy();
      chartInstance.current = null;
      return;
    }

    // Initialize chart library
    chartInstance.current = new Chart(canvas, {
      type: 'line',
      data: data,
    });
  }, [data]);

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

// Video player
function VideoPlayer({ src }) {
  const playerRef = useCallback((video: HTMLVideoElement | null) => {
    if (!video) return;

    // Initialize video player library
    const player = new VideoJS(video, {
      controls: true,
      autoplay: false,
    });

    return () => player.dispose();
  }, []);

  return (
    <video ref={playerRef} className="video-js">
      <source src={src} type="video/mp4" />
    </video>
  );
}

Merging Refs#

import { useCallback, useRef, forwardRef } from 'react';

// Merge multiple refs
function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]) {
  return (node: T | null) => {
    refs.forEach((ref) => {
      if (typeof ref === 'function') {
        ref(node);
      } else if (ref) {
        (ref as React.MutableRefObject<T | null>).current = node;
      }
    });
  };
}

// Component with internal and forwarded ref
const Input = forwardRef<HTMLInputElement, InputProps>((props, forwardedRef) => {
  const internalRef = useRef<HTMLInputElement>(null);

  const measureRef = useCallback((node: HTMLInputElement | null) => {
    if (node) {
      console.log('Input width:', node.offsetWidth);
    }
  }, []);

  return (
    <input
      ref={mergeRefs(forwardedRef, internalRef, measureRef)}
      {...props}
    />
  );
});

Best Practices#

Usage:
✓ Use for measurement/observers
✓ Use for dynamic element lists
✓ Use for third-party integrations
✓ Wrap in useCallback when needed

Cleanup:
✓ Handle null (element unmounted)
✓ Disconnect observers
✓ Dispose library instances
✓ Clear stored references

Performance:
✓ Memoize with useCallback
✓ Avoid creating refs in loops
✓ Use Map for dynamic refs
✓ Batch state updates

Avoid:
✗ Side effects without cleanup
✗ Recreating refs unnecessarily
✗ Forgetting null checks
✗ Complex logic in callbacks

Ref callbacks provide fine-grained control for measuring elements, managing observers, and integrating third-party libraries. Use them when useRef isn't flexible enough, especially for dynamic lists and elements that need setup/cleanup logic. Always handle the null case for proper cleanup.