Refs and DOM Access

Imperative escape hatches for DOM nodes and mutable values that should not trigger re-renders.

useRef Mutable Box

useRef holds a .current value that persists across renders without causing updates when it changes.

const renderCount = useRef(0);
renderCount.current += 1;

Focusing an Input

Attach a ref to an input and call .focus() in a handler or effect after the node exists.

const inputRef = useRef<HTMLInputElement>(null);
function focusSearch() {
  inputRef.current?.focus();
}
return <input ref={inputRef} />;

Measuring a Node

Read layout from the DOM after commit. Prefer measuring in an event or layout effect when size drives UI.

const boxRef = useRef<HTMLDivElement>(null);
function measure() {
  return boxRef.current?.getBoundingClientRect();
}

Storing Previous Value

Keep the last render's value in a ref so you can compare without forcing another state update.

const prev = useRef(value);
useEffect(() => {
  prev.current = value;
}, [value]);
const previous = prev.current;

Interval Id in a Ref

Store timer ids in a ref so handlers can clear the latest timer without re-creating closures every tick.

const timerRef = useRef<number | null>(null);
function schedule() {
  if (timerRef.current) window.clearTimeout(timerRef.current);
  timerRef.current = window.setTimeout(run, 300);
}

Callback Ref

A function ref runs when the node attaches or detaches. Use it when you need setup tied to the actual DOM lifetime.

const setCanvas = useCallback((node: HTMLCanvasElement | null) => {
  if (node) initChart(node);
  else destroyChart();
}, []);
return <canvas ref={setCanvas} />;

Forwarding Refs with forwardRef

Legacy pattern to expose a child DOM node to a parent. Still valid; React 19 also allows ref as a normal prop on function components.

const Field = forwardRef<HTMLInputElement, FieldProps>(function Field(props, ref) {
  return <input ref={ref} {...props} />;
});

useImperativeHandle

Customize what a parent receives when it holds a ref to your component - expose methods instead of the raw DOM node.

useImperativeHandle(ref, () => ({
  focus: () => inputRef.current?.focus(),
  clear: () => setValue(""),
}));

Ref as Instance Field

Mirror the latest callback into a ref so a long-lived subscription always calls current logic without resubscribing.

const onMessageRef = useRef(onMessage);
onMessageRef.current = onMessage;
useEffect(() => socket.on("msg", (m) => onMessageRef.current(m)), [socket]);

Avoid Reading Ref During Render

Writing/reading refs during render for control flow fights React's model. Prefer state for anything that should appear on screen.

// Good: read ref in handler
function onClick() {
  console.log(ref.current?.value);
}

Scroll Into View

Imperatively scroll a list item into view after selection or navigation.

const itemRef = useRef<HTMLLIElement>(null);
useEffect(() => {
  if (selected) itemRef.current?.scrollIntoView({ block: "nearest" });
}, [selected]);

Video Play Pause

Media elements expose imperative APIs. Drive play/pause from effects or handlers via a ref.

const videoRef = useRef<HTMLVideoElement>(null);
useEffect(() => {
  if (playing) void videoRef.current?.play();
  else videoRef.current?.pause();
}, [playing]);

Form Reset via Ref

Call native reset() when you need the browser to clear uncontrolled fields, or reset controlled state instead.

const formRef = useRef<HTMLFormElement>(null);
function onClear() {
  formRef.current?.reset();
}

Shared Ref Across Effects

One ref can be read from multiple effects and handlers. It is a shared mutable cell for the component instance.

const nodeRef = useRef<HTMLDivElement>(null);
useEffect(() => observe(nodeRef.current), []);
useEffect(() => highlight(nodeRef.current, active), [active]);

Ref Cleanup on Unmount

Always null-check .current. After unmount, React sets host refs to null; async work must tolerate that.

useEffect(() => {
  let alive = true;
  load().then((data) => {
    if (alive) apply(ref.current, data);
  });
  return () => {
    alive = false;
  };
}, []);

Related

• Effects and Side Effects - where most ref reads/writes belong
• Forms and Controlled Inputs - uncontrolled fields often use refs
• React 19 APIs - ref as a regular prop without forwardRef

External Related Links

• react.dev/reference - pure API reference (Hooks, built-in components, directives)
• react.dev - official React docs (Learn + full API reference)
• MDN Web Docs - authoritative HTML/CSS/JS reference

Stack versions: React 19 · TypeScript (strict) · DOM typings via lib.dom