React Ref Patterns

Refs provide direct access to DOM elements and persist values across renders. Here's how to use them.

Basic useRef#

import { useRef, useEffect } from 'react';

function TextInput() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    // Focus input on mount
    inputRef.current?.focus();
  }, []);

  return <input ref={inputRef} type="text" />;
}

// Storing mutable values
function Timer() {
  const intervalRef = useRef<number | null>(null);
  const [count, setCount] = useState(0);

  useEffect(() => {
    intervalRef.current = window.setInterval(() => {
      setCount(c => c + 1);
    }, 1000);

    return () => {
      if (intervalRef.current) {
        clearInterval(intervalRef.current);
      }
    };
  }, []);

  const stop = () => {
    if (intervalRef.current) {
      clearInterval(intervalRef.current);
    }
  };

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={stop}>Stop</button>
    </div>
  );
}

forwardRef#

import { forwardRef, useRef } from 'react';

// Forward ref to inner element
const FancyInput = forwardRef<HTMLInputElement, { label: string }>(
  function FancyInput({ label }, ref) {
    return (
      <div className="fancy-input">
        <label>{label}</label>
        <input ref={ref} type="text" />
      </div>
    );
  }
);

// Usage
function Form() {
  const inputRef = useRef<HTMLInputElement>(null);

  const focus = () => {
    inputRef.current?.focus();
  };

  return (
    <div>
      <FancyInput ref={inputRef} label="Name" />
      <button onClick={focus}>Focus</button>
    </div>
  );
}

// Forward ref with generic types
interface InputProps<T> {
  value: T;
  onChange: (value: T) => void;
}

const GenericInput = forwardRef(function GenericInput<T>(
  props: InputProps<T>,
  ref: React.ForwardedRef<HTMLInputElement>
) {
  return <input ref={ref} />;
});

useImperativeHandle#

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

interface ModalHandle {
  open: () => void;
  close: () => void;
}

const Modal = forwardRef<ModalHandle, { children: React.ReactNode }>(
  function Modal({ children }, ref) {
    const [isOpen, setIsOpen] = useState(false);

    useImperativeHandle(ref, () => ({
      open: () => setIsOpen(true),
      close: () => setIsOpen(false),
    }), []);

    if (!isOpen) return null;

    return (
      <div className="modal">
        {children}
        <button onClick={() => setIsOpen(false)}>Close</button>
      </div>
    );
  }
);

// Usage
function App() {
  const modalRef = useRef<ModalHandle>(null);

  return (
    <div>
      <button onClick={() => modalRef.current?.open()}>
        Open Modal
      </button>
      <Modal ref={modalRef}>
        <h2>Modal Content</h2>
      </Modal>
    </div>
  );
}

// Video player example
interface VideoPlayerHandle {
  play: () => void;
  pause: () => void;
  seek: (time: number) => void;
  getCurrentTime: () => number;
}

const VideoPlayer = forwardRef<VideoPlayerHandle, { src: string }>(
  function VideoPlayer({ src }, ref) {
    const videoRef = useRef<HTMLVideoElement>(null);

    useImperativeHandle(ref, () => ({
      play: () => videoRef.current?.play(),
      pause: () => videoRef.current?.pause(),
      seek: (time) => {
        if (videoRef.current) {
          videoRef.current.currentTime = time;
        }
      },
      getCurrentTime: () => videoRef.current?.currentTime ?? 0,
    }), []);

    return <video ref={videoRef} src={src} />;
  }
);

Ref Callbacks#

// Callback ref for dynamic refs
function MeasureExample() {
  const [height, setHeight] = useState(0);

  const measuredRef = useCallback((node: HTMLDivElement | null) => {
    if (node !== null) {
      setHeight(node.getBoundingClientRect().height);
    }
  }, []);

  return (
    <div>
      <div ref={measuredRef}>Content to measure</div>
      <p>Height: {height}px</p>
    </div>
  );
}

// Multiple refs for list items
function ListWithRefs() {
  const itemRefs = useRef<Map<string, HTMLLIElement>>(new Map());

  const setItemRef = useCallback((id: string, 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={(node) => setItemRef(item.id, node)}
        >
          {item.name}
        </li>
      ))}
    </ul>
  );
}

Combining Multiple Refs#

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

// Usage
const Input = forwardRef<HTMLInputElement, InputProps>(
  function Input(props, forwardedRef) {
    const localRef = useRef<HTMLInputElement>(null);
    const mergedRef = useMergeRefs(localRef, forwardedRef);

    useEffect(() => {
      // Can use localRef internally
      localRef.current?.focus();
    }, []);

    return <input ref={mergedRef} {...props} />;
  }
);

Ref with Intersection Observer#

function useIntersectionObserver<T extends Element>(
  options?: IntersectionObserverInit
) {
  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
  const elementRef = useRef<T | null>(null);

  useEffect(() => {
    const element = elementRef.current;
    if (!element) return;

    const observer = new IntersectionObserver(
      ([entry]) => setEntry(entry),
      options
    );

    observer.observe(element);
    return () => observer.disconnect();
  }, [options?.root, options?.rootMargin, options?.threshold]);

  return { ref: elementRef, entry };
}

// Usage
function LazyImage({ src, alt }: { src: string; alt: string }) {
  const { ref, entry } = useIntersectionObserver<HTMLImageElement>({
    rootMargin: '100px',
  });

  const isVisible = entry?.isIntersecting ?? false;

  return (
    <img
      ref={ref}
      src={isVisible ? src : undefined}
      alt={alt}
      loading="lazy"
    />
  );
}

Previous Value Ref#

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T>();

  useEffect(() => {
    ref.current = value;
  }, [value]);

  return ref.current;
}

// Usage
function Counter() {
  const [count, setCount] = useState(0);
  const prevCount = usePrevious(count);

  return (
    <div>
      <p>Current: {count}, Previous: {prevCount ?? 'N/A'}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}

Latest Value Ref#

// Keep ref in sync with latest value
function useLatest<T>(value: T) {
  const ref = useRef(value);
  ref.current = value;
  return ref;
}

// Usage in callbacks
function Search({ onSearch }: { onSearch: (query: string) => void }) {
  const [query, setQuery] = useState('');
  const onSearchRef = useLatest(onSearch);

  useEffect(() => {
    const timeoutId = setTimeout(() => {
      onSearchRef.current(query);
    }, 300);

    return () => clearTimeout(timeoutId);
  }, [query]);

  return (
    <input
      value={query}
      onChange={e => setQuery(e.target.value)}
    />
  );
}

DOM Manipulation#

function ScrollContainer() {
  const containerRef = useRef<HTMLDivElement>(null);

  const scrollToTop = () => {
    containerRef.current?.scrollTo({
      top: 0,
      behavior: 'smooth',
    });
  };

  const scrollToBottom = () => {
    if (containerRef.current) {
      containerRef.current.scrollTop = containerRef.current.scrollHeight;
    }
  };

  return (
    <div>
      <div ref={containerRef} className="scroll-container">
        {/* Content */}
      </div>
      <button onClick={scrollToTop}>Scroll to Top</button>
      <button onClick={scrollToBottom}>Scroll to Bottom</button>
    </div>
  );
}

// Focus management
function FocusManager() {
  const firstRef = useRef<HTMLButtonElement>(null);
  const lastRef = useRef<HTMLButtonElement>(null);

  const handleKeyDown = (e: React.KeyboardEvent) => {
    if (e.key === 'Tab') {
      if (e.shiftKey && document.activeElement === firstRef.current) {
        e.preventDefault();
        lastRef.current?.focus();
      } else if (!e.shiftKey && document.activeElement === lastRef.current) {
        e.preventDefault();
        firstRef.current?.focus();
      }
    }
  };

  return (
    <div onKeyDown={handleKeyDown}>
      <button ref={firstRef}>First</button>
      <button>Middle</button>
      <button ref={lastRef}>Last</button>
    </div>
  );
}

Canvas Ref#

function Canvas() {
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;

    const ctx = canvas.getContext('2d');
    if (!ctx) return;

    // Draw
    ctx.fillStyle = 'blue';
    ctx.fillRect(10, 10, 100, 100);
  }, []);

  return <canvas ref={canvasRef} width={500} height={500} />;
}

Best Practices#

Usage:
✓ Use refs for DOM access
✓ Store mutable values that don't trigger renders
✓ Use forwardRef for reusable components
✓ Prefer controlled components when possible

Patterns:
✓ useImperativeHandle for custom API
✓ Callback refs for measurement
✓ Merge refs when needed
✓ Keep refs stable

Avoid:
✗ Overusing refs for state
✗ Directly mutating DOM in render
✗ Ignoring null checks
✗ Creating refs in loops without keys

Refs enable direct DOM access and mutable value storage. Use forwardRef for component composition, useImperativeHandle for custom APIs, and callback refs for dynamic scenarios. Always handle null cases and prefer React's declarative patterns when possible.