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.
<div ref={(node) => { console.log('attached', node); return () => console.log('detached'); }} />
Try it
Syntax
<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 inuseCallbackwhen it does real work. - Prefer cleanup over
nullchecks. The cleanup function is the right place to disconnect an observer, remove a listener or delete a map entry. It also captures the specificnodeit was created for. - Use state to learn about a node.
const [node, setNode] = useState(null)withref={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
useRefarrays 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
setStateunconditionally in a ref callback that runs every render (a new inline function plussetStatewith a new value loops forever). Guard against identical values or use a stable callback.
Related
ref, useRef, useCallback, useLayoutEffect- Lessons: Refs and imperative handles, useRef