External DOM integration
Register or unregister a DOM node with an external system when it appears or disappears.
React 19+ · Type Alias
RefCallback
RefCallback is the function form of a React ref. React calls it with the attached DOM node and, in React 19, can run a cleanup function returned by the callback when the node detaches.
- Since
- 19
How it works
RefCallback is the callback form of a React ref. React invokes it with the referenced value when attaching, and in React 19 a returned cleanup function runs when the ref detaches; if no cleanup is returned, React uses null for detachment.
Syntax
(node: T | null) => void | (() => void)Parameters
| Name | Type | Description |
|---|---|---|
node | DOM node | The referenced DOM node supplied when the callback ref attaches; the page documents this as a DOM node. |
Returns
An optional cleanup function. React calls it when the ref is detached; if omitted, React calls the callback with null on detachment.
Key points
- A callback ref is an alternative to passing a ref object and is useful when attachment itself should trigger imperative work.
- React supplies the attached DOM node to the callback when the element enters the screen.
- React 19 runs the returned cleanup when the referenced node is removed.
- Changing the callback identity causes React to process the ref again, which can repeat setup and cleanup.
- Without a returned cleanup function, detachment is signaled by calling the callback with null.
- Treat callback refs as setup-and-cleanup lifecycles, especially when they interact with systems outside React.
Common mistakes
- Strict Mode deliberately exercises callback-ref setup and cleanup an extra time in development, so cleanup must fully undo setup.
Example: Callback ref with cleanup
import { useState } from 'react';
export default function App() {
const [node, setNode] = useState<HTMLInputElement | null>(null);
return (
<label>
Name
<input
ref={(element) => {
setNode(element);
return () => setNode(null);
}}
/>
<span>{node ? 'Attached' : 'Detached'}</span>
</label>
);
}The callback receives the input element when React attaches the ref and returns cleanup that runs when React detaches it.
When to use it
Imperative node setup
Measure, focus, observe, or otherwise act on a node immediately after attachment.
Dynamic lists
Track a dynamic collection of nodes where each item needs attachment-specific registration.
Interview questions
QWhat is a callback ref, and what does it receive?
A callback ref is a function passed to ref instead of a ref object. React calls it with the DOM node when attached; in React 19, the callback can return cleanup that runs when detached.
Follow-up: What happens without returned cleanup? React calls the callback with null on detachment, so code must handle that value or use the React 19 cleanup form.
QWhy can an inline callback ref run during rerenders?
React compares callback identity. If a different callback is supplied, React cleans up the old ref and attaches the new one; an inline function can therefore cause repeated setup during rerenders.
Follow-up: How can repeated work be avoided? Reuse the callback function reference, for example by defining it stably or memoizing it when appropriate.
QWhy is cleanup especially important with Strict Mode?
Callback refs need symmetric cleanup because setup may run more than once in development Strict Mode. Returning cleanup that reverses subscriptions, registrations, or other effects prevents leaks and exposes bugs early.
Follow-up: What kind of bug does missing cleanup cause? External registrations can accumulate across setup cycles, producing stale references, memory leaks, or duplicated behavior.
Related
useRefcreateRefuseImperativeHandleStrictModeref