React useRef and DOM Manipulation

A comprehensive guide to react useref and dom manipulation with production examples and best practices.

What is useRef? The Mutable Ref Object

useRef is a React hook that returns a mutable ref object whose .current property is initialized to the passed argument. Unlike state, changing .current does not cause a re-render. This makes useRef ideal for storing values that persist across renders without triggering updates. The ref object itself is stable across the component's lifecycle — the same object reference is returned on every render. This stability is key for DOM access, as it allows you to attach a ref to a JSX element and reliably access the underlying DOM node after mounting. useRef is not just for DOM; it can hold any mutable value, like timers, previous state, or instance variables. However, its most common use case is direct DOM manipulation, which we'll explore in depth.

import { useRef, useEffect } from 'react';

export default function InputFocus() {
  const inputRef = useRef(null);

  useEffect(() => {
    // inputRef.current is the DOM node after mount
    inputRef.current?.focus();
  }, []);

  return <input ref={inputRef} type="text" placeholder="Auto-focused" />;
}

Accessing DOM Nodes with the ref Attribute

React provides a built-in ref attribute on host elements (like <div>, <input>, etc.) that accepts a ref object. When the element mounts, React sets ref.current to the corresponding DOM node. When the element unmounts, it sets ref.current back to null. This is the primary way to get a handle on a DOM element for imperative operations like focusing, measuring, or animating. You can also use callback refs for more control, but the object ref is simpler and sufficient for most cases. Important: ref only works on host elements, not on custom components unless they forward refs using forwardRef. We'll cover that later.

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

export default function MeasureExample() {
  const divRef = useRef(null);
  const [height, setHeight] = useState(0);

  useEffect(() => {
    if (divRef.current) {
      setHeight(divRef.current.getBoundingClientRect().height);
    }
  }, []);

  return (
    <>
      <div ref={divRef} style={{ padding: '20px', background: '#eee' }}>
        This div's height is measured.
      </div>
      <p>Height: {height}px</p>
    </>
  );
}

Imperative DOM Manipulation: When and How

React is declarative — you describe what the UI should look like, and React handles the DOM updates. However, some operations are inherently imperative: focusing an input, scrolling to a position, playing a video, or integrating with a third-party library that expects a DOM node. useRef gives you an escape hatch for these cases. The rule of thumb: if you can do it declaratively (e.g., using state to control visibility), do it declaratively. Use imperative refs only when there's no declarative equivalent. Common patterns include auto-focus on mount, managing media playback, and triggering animations. Always clean up any side effects (like event listeners) in the useEffect cleanup function to avoid memory leaks.

import { useRef } from 'react';

export default function VideoPlayer({ src }) {
  const videoRef = useRef(null);

  const handlePlay = () => videoRef.current?.play();
  const handlePause = () => videoRef.current?.pause();

  return (
    <div>
      <video ref={videoRef} src={src} width={400} />
      <button onClick={handlePlay}>Play</button>
      <button onClick={handlePause}>Pause</button>
    </div>
  );
}

Forwarding Refs to Custom Components

By default, refs are not passed to custom components — they only work on host elements. To expose a DOM node from a child component, you must use React.forwardRef. This higher-order component receives props and ref as arguments, allowing you to attach the ref to a host element inside the child. This is essential for building reusable component libraries where consumers need direct access to the underlying DOM (e.g., for focus management or tooltip positioning). Without forwardRef, you'd have to use callback refs or prop drilling, which is messy. forwardRef is the standard pattern.

import { forwardRef } from 'react';

const FancyInput = forwardRef((props, ref) => {
  return <input ref={ref} className="fancy" {...props} />;
});

export default function Parent() {
  const inputRef = useRef(null);

  useEffect(() => {
    inputRef.current?.focus();
  }, []);

  return <FancyInput ref={inputRef} placeholder="Focused via forwardRef" />;
}

Storing Mutable Values Without Re-renders

Beyond DOM access, useRef can store any mutable value that you want to persist across renders without causing re-renders. Common use cases: holding interval IDs, previous state values, or flags that track whether a component is mounted. Because changing .current doesn't trigger a re-render, it's more performant than useState for values that don't affect the UI. However, be careful: mutating refs doesn't notify React, so the UI won't update automatically. If you need the UI to reflect the value, use state instead. A classic pattern is using a ref to store the previous value of a state variable for comparison in useEffect.

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

export default function Counter() {
  const [count, setCount] = useState(0);
  const prevCountRef = useRef();

  useEffect(() => {
    prevCountRef.current = count;
  });

  const prevCount = prevCountRef.current;

  return (
    <div>
      <p>Now: {count}, before: {prevCount ?? 'none'}</p>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}

useRef vs useState: When to Use Which

A common confusion is when to use useRef vs useState. The key difference: useState triggers a re-render when the value changes; useRef does not. If the value affects the UI, use state. If it's a value that only needs to be read or written in effects/event handlers (like timers, DOM nodes, or previous values), use ref. Using state for non-UI values causes unnecessary re-renders and performance issues. Conversely, using ref for UI values means the UI won't update. A good rule: if you need the component to re-render when the value changes, use state; otherwise, use ref.

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

export default function Timer() {
  const [seconds, setSeconds] = useState(0);
  const intervalRef = useRef(null);

  const start = () => {
    if (intervalRef.current) return;
    intervalRef.current = setInterval(() => {
      setSeconds(s => s + 1);
    }, 1000);
  };

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

  useEffect(() => () => clearInterval(intervalRef.current), []);

  return (
    <div>
      <p>{seconds}s</p>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
    </div>
  );
}

Callback Refs: Fine-Grained Control

React also supports callback refs — a function instead of a ref object. React calls the function with the DOM node when the element mounts, and with null when it unmounts. Callback refs give you more control, especially when you need to run logic on every ref change (e.g., when the ref is attached to a dynamic list of items). They also allow you to clean up previous refs. However, they can cause more re-renders if not memoized. Use useCallback to stabilize the callback ref and avoid unnecessary invocations. Callback refs are useful for measuring dynamic content or integrating with libraries that need a node reference.

import { useState, useCallback } from 'react';

export default function List() {
  const [items, setItems] = useState(['Item 1', 'Item 2']);
  const [heights, setHeights] = useState([]);

  const measureRef = useCallback((node) => {
    if (node !== null) {
      setHeights(prev => [...prev, node.getBoundingClientRect().height]);
    }
  }, []);

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

Common Pitfalls and Anti-Patterns

Even experienced developers make mistakes with useRef. Common pitfalls: (1) Reading ref.current during render — it may be null or stale. Always access in effects or handlers. (2) Using refs to store state that should trigger re-renders — leads to stale UI. (3) Forgetting to clean up refs on unmount, causing memory leaks (e.g., not clearing intervals). (4) Overusing refs for DOM manipulation when a declarative approach exists — makes code harder to maintain. (5) Mutating refs inside render — can cause inconsistencies. Stick to the patterns: refs for DOM access and mutable values, state for UI. Test your ref logic with strict mode to catch double-mount issues.

// BAD: reading ref during render
function BadComponent() {
  const ref = useRef(null);
  // ref.current is null on first render
  const width = ref.current?.offsetWidth; // undefined
  return <div ref={ref}>Width: {width}</div>;
}

// GOOD: read in effect
function GoodComponent() {
  const ref = useRef(null);
  const [width, setWidth] = useState(0);
  useEffect(() => {
    setWidth(ref.current?.offsetWidth ?? 0);
  }, []);
  return <div ref={ref}>Width: {width}</div>;
}

createRef vs useRef: Class Component Legacy

In React class components, refs are created using React.createRef(). This method returns a ref object with a current property, similar to useRef in functional components. However, createRef is only available in class components and is not a hook. The key difference is that createRef creates a new ref object on every render, while useRef persists the same ref object across renders. In functional components, useRef is the standard approach because it leverages hooks and avoids unnecessary object creation. createRef exists primarily for legacy class component support. If you're migrating from class to functional components, replace React.createRef() with useRef(null). Note that createRef cannot be used inside functional components; doing so will cause a warning and break ref persistence. For new code, always prefer useRef.

import React, { Component } from 'react';

class MyComponent extends Component {
  constructor(props) {
    super(props);
    this.myRef = React.createRef();
  }

  componentDidMount() {
    console.log(this.myRef.current); // DOM node
  }

  render() {
    return <div ref={this.myRef}>Hello</div>;
  }
}

flushSync: Coordinating Ref Access with DOM Updates

React batches state updates and defers DOM commits for performance. This means after calling setState, the DOM may not be updated immediately, so reading a ref's current property might return stale data. flushSync from react-dom forces React to flush any pending updates and update the DOM synchronously before proceeding. This is useful when you need to measure DOM properties (e.g., scroll position, element dimensions) immediately after a state change. However, use flushSync sparingly as it can degrade performance by bypassing batching. Example: after adding an item to a list, you want to scroll to the new item. Without flushSync, scrollIntoView might run before the new element is rendered. Wrap the state update and ref access in flushSync to ensure the DOM is up-to-date.

import React, { useRef, useState } from 'react';
import { flushSync } from 'react-dom';

function ScrollList() {
  const [items, setItems] = useState(['Item 1']);
  const listEndRef = useRef(null);

  const addItem = () => {
    flushSync(() => {
      setItems(prev => [...prev, `Item ${prev.length + 1}`]);
    });
    // DOM is now updated, ref points to new element
    listEndRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  return (
    <div>
      <ul>
        {items.map((item, index) => (
          <li key={index}>{item}</li>
        ))}
        <li ref={listEndRef} />
      </ul>
      <button onClick={addItem}>Add Item</button>
    </div>
  );
}

ResizeObserver + useRef for Responsive Layout

ResizeObserver is a browser API that watches for changes to an element's size. Combined with useRef, you can create responsive components that react to container size changes without relying on window resize events. This is ideal for charts, grids, or any layout that needs to adapt to its container. Use useRef to hold a reference to the observed element and store the observer instance. In a useEffect, create the observer, attach it to the ref's current node, and update state with new dimensions. Clean up by disconnecting the observer on unmount. Example: a responsive card that changes its layout based on width. Note that ResizeObserver is supported in modern browsers; for older ones, consider a polyfill.

import React, { useRef, useState, useEffect } from 'react';

function ResponsiveCard() {
  const cardRef = useRef(null);
  const [width, setWidth] = useState(0);

  useEffect(() => {
    const observer = new ResizeObserver(entries => {
      for (let entry of entries) {
        setWidth(entry.contentRect.width);
      }
    });

    if (cardRef.current) {
      observer.observe(cardRef.current);
    }

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

  return (
    <div ref={cardRef} style={{ padding: '1rem', border: '1px solid #ccc' }}>
      {width > 400 ? (
        <div style={{ display: 'flex' }}>
          <div>Wide layout</div>
          <div>Additional content</div>
        </div>
      ) : (
        <div>Narrow layout</div>
      )}
      <p>Current width: {Math.round(width)}px</p>
    </div>
  );
}