Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Props and Attributes

React ref callback functions

Reference for React ref callback functions: when they run, the React 19 cleanup return value, null detach calls, keeping nodes in a Map, and stable callbacks.

Instead of a ref object you can pass a function as the ref prop. React calls it with the DOM node when the element is added to the page, which lets you run code at that exact moment: measure the node, start an observer, register it in a collection or focus it. It is the most direct way to say "do something when this element appears".

In React 19 the function may return a cleanup function. React calls that cleanup when the element is removed or when the ref callback changes, in the same way an effect cleanup works. A callback that returns nothing is also called with null on detach, as in earlier versions.

JSX
<div
  ref={(node) => {
    console.log('attached', node);
    return () => console.log('detached');
  }}
/>

Try it

Attach, cleanup and a stable callback
Collecting refs for a list in a Map

Syntax

JSX
<element ref={(node) => void | (() => void)} />
Name Description
node The DOM element (or class component instance) that was attached.
Return value Optional. A cleanup function that React calls when the element is detached or when the ref callback is replaced by a different function.

When it runs: during the commit, after the element is in the DOM and before the browser paints. It runs again whenever the callback function identity changes.

Legacy form: if the callback does not return a function, React calls it with null when the element goes away (and when the callback is replaced, first with null and then with the new node).

Errors / edge cases: a returned value that is not a function is ignored at runtime, but TypeScript's React 19 types reject it, which catches the classic implicit-return mistake. Write the body with braces: ref={(node) => { cache = node; }} rather than ref={(node) => (cache = node)}.

Usage notes

  • Inline arrow functions are new every render. React treats a changed callback as a new ref: it runs the old cleanup (or calls the old function with null) and calls the new function with the node again, on every render. That is harmless for a cheap assignment, but expensive for observers. Wrap the callback in useCallback when it does real work.
  • Prefer cleanup over null checks. The cleanup function is the right place to disconnect an observer, remove a listener or delete a map entry. It also captures the specific node it was created for.
  • Use state to learn about a node. const [node, setNode] = useState(null) with ref={setNode} re-renders once when the node attaches, so the next render can use it. Do this when rendering depends on the measurement.
  • Dynamic collections. A Map filled by callback refs (second example) works for lists whose length changes, which useRef arrays cannot do cleanly.
  • Order. When elements attach, a child's ref callback runs before its parent's. During an update, cleanups of the old callbacks run before the new callbacks attach.
  • StrictMode in development attaches, detaches and attaches again to expose missing cleanup. Make attach and cleanup symmetric and the double run is invisible.
  • Attach to real elements. A <Fragment> has no DOM node of its own, so put the ref on an element inside it.
  • Do not call setState unconditionally in a ref callback that runs every render (a new inline function plus setState with a new value loops forever). Guard against identical values or use a stable callback.