Typing Refs

Recipe

Type useRef correctly for DOM element references and mutable value containers. Understand the difference between read-only DOM refs and mutable refs, and when to use each.

Working Example

// DOM element ref (read-only .current)
function TextInput() {
  const inputRef = useRef<HTMLInputElement>(null);
 
  const focusInput = () => {
    inputRef.current?.focus();
  };
 
  return (
    <div>
      <input ref={inputRef} type="text" />
      <button onClick={focusInput}>Focus Input</button>
    </div>
  );
}

// Mutable ref (writable .current)
function Timer() {
  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
  const [count, setCount] = useState(0);
 
  const start = () => {
    if (intervalRef.current) return;
    intervalRef.current = setInterval(() => {
      setCount((c) => c + 1);
    }, 1000);
  };
 
  const stop = () => {
    if (intervalRef.current) {
      clearInterval(intervalRef.current);
      intervalRef.current = null;
    }
  };
 
  return (
    <div>
      <p>{count}</p>
      <button onClick={start}>Start</button>
      <button onClick={stop}>Stop</button>
    </div>
  );
}

Deep Dive

How It Works

• useRef<HTMLInputElement>(null) creates a ref object with { current: HTMLInputElement | null }. When passed to a JSX ref attribute, React manages setting .current to the DOM node.
• In React 19, ref is a regular prop rather than a special attribute. Function components can accept ref directly in their props without forwardRef.
• For mutable refs (storing timers, previous values, etc.), initialize with null and type accordingly: useRef<NodeJS.Timeout | null>(null).
• The distinction between DOM refs and mutable refs is conceptual. Both use useRef. The difference is whether React manages .current (DOM ref) or you manage it yourself (mutable ref).

Variations

Storing previous value:

function usePrevious<T>(value: T): T | undefined {
  const ref = useRef<T | undefined>(undefined);
 
  useEffect(() => {
    ref.current = value;
  });
 
  return ref.current;
}

Ref callback pattern:

function MeasuredBox() {
  const [height, setHeight] = useState(0);
 
  const measuredRef = (node: HTMLDivElement | null) => {
    if (node) {
      setHeight(node.getBoundingClientRect().height);
    }
  };
 
  return (
    <div ref={measuredRef}>
      <p>This box is {height}px tall</p>
    </div>
  );
}

Video element ref:

const videoRef = useRef<HTMLVideoElement>(null);
 
// Play/pause
const togglePlay = () => {
  if (videoRef.current?.paused) {
    videoRef.current.play();
  } else {
    videoRef.current?.pause();
  }
};

TypeScript Notes

• Common DOM ref types: HTMLDivElement, HTMLInputElement, HTMLButtonElement, HTMLFormElement, HTMLCanvasElement, HTMLVideoElement, SVGSVGElement.
• ReturnType<typeof setInterval> is portable across Node and browser environments instead of hardcoding NodeJS.Timeout or number.
• In React 19, forwardRef is no longer necessary. Components can accept ref as a regular prop: function Input({ ref }: { ref?: React.Ref<HTMLInputElement> }).

Gotchas

• Accessing inputRef.current without a null check will error under strictNullChecks. Always use optional chaining (?.) or a guard.
• Assigning to .current on a DOM ref managed by React has no effect. React overwrites it during rendering.
• Using useRef<HTMLInputElement>(null!) (non-null assertion) removes the need for null checks but hides potential bugs if the ref is accessed before mount.
• Ref callbacks fire with null when the component unmounts. Always handle the null case.

Alternatives

FAQs

const videoRef = useRef<HTMLVideoElement>(null);

function Input({ ref }: { ref?: React.Ref<HTMLInputElement> }) { ... }

Related

• Typing Events
• Typing Props
• Generics
• TypeScript Basics