useRef: values that survive without rendering

useRef(initial) returns an object { current: initial }. React hands back the same object on every render of that component, and changing ref.current is an ordinary property write: React does not know about it and does not re-render.

That puts a ref between the two other places a component can keep a value:

1// A miniature host: the hook slots persist, the function body re-runs.2function createHost(component) {3  const slots = { state: 0, ref: { current: 0 } };4  const screen = [];5  let handlers;6  const renderOnce = () => {7    handlers = component(slots, () => renderOnce());8    screen.push(handlers.output);9  };10  renderOnce();11  return { click: (name) => handlers[name](), screen };12}13 14function Clicker(slots, rerender) {15  let local = 0;                      // a plain variable16  const ref = slots.ref;              // useRef(0): same object every render17  const count = slots.state;          // useState(0)18  return {19    output: `state=${count} ref=${ref.current} local=${local}`,20    local: () => { local++; },21    ref: () => { ref.current++; },22    state: () => { slots.state = count + 1; rerender(); },23  };24}25 26export function run() {27  const host = createHost(Clicker);28  host.click("ref");29  host.click("ref");30  host.click("local");31  host.click("state");32  return host.screen;33}

The ref counted every click, but the screen kept showing the value from the last render until something else (the state click) caused one. The local variable was back to 0 because each render runs the function body from the top.

Use a ref for values the component needs to remember but that do not affect what it renders: a timer id, the previous value of a prop, a flag for "request in flight", an instance of a third-party object. If the value appears in the JSX, it should be state.

Do not read or write refs during render

Rendering must be pure. Reading ref.current in the JSX shows whatever the last mutation left there, which may not correspond to any render. Read and write refs in event handlers and effects. The one accepted exception is lazy initialisation: if (ref.current === null) ref.current = new Player().

The latest value inside an old closure

The previous lesson's stale closures have a ref-based fix: write the newest value into a ref after every render, and have the long-lived callback read ref.current instead of the captured variable.

1export function run() {2  const latest = { current: null };   // useRef(null)3  const callbacks = [];4  const renders = ["draft 1", "draft 2", "draft 3"];5 6  renders.forEach((text, i) => {7    latest.current = text;            // updated after every render8    if (i === 0) {9      // Set up once, like an effect with [] dependencies:10      callbacks.push(() => `captured: ${text}`);11      callbacks.push(() => `via ref: ${latest.current}`);12    }13  });14 15  // The timer fires after the third render:16  return callbacks.map((f) => f());17}

Refs to DOM nodes

Passing a ref object as the ref attribute of a DOM element asks React to put the DOM node in ref.current when it is attached, and to set it back to null when it is removed:

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

The node is only there after commit, so use it in handlers and effects, never during render. In React 19, a function component receives ref as a normal prop and can pass it on to an inner element — forwardRef is no longer needed for that. A ref callback (ref={node => …}) is called with the node, and in React 19 it may return a cleanup function that runs when the node is detached. To expose only a few methods instead of the whole node, a component can use useImperativeHandle.

Common mistakes

• Rendering a value kept in a ref. It goes stale on screen, because changing the ref never triggers a render, as the example models.
• Using a plain let to remember something between renders. It is reset every render.
• Reading ref.current of a DOM ref during the first render. It is still null; the node is attached at commit.
• expecting the effect to re-run when changes. Mutating triggers nothing.