useImperativeHandle: expose an API, not a ref

useImperativeHandle replaces a ref value with an object you choose: the parent calls explicit methods and never receives the DOM node. It pays off when the public API must stay narrower than the element's own.

What a ref really carries

A plain ref points at the element: whoever receives it can call focus, remove it from the DOM, rewrite its attributes. That power is wider than the component wants to hand out, and every method the parent uses becomes a coupling no type checks.

Two methods, on purpose

A text field that exposes the selection without handing over the input:

const TextField = forwardRef(function TextField({ label }, ref) {
  const inputRef = useRef(null);

  // The parent gets focus and selectAll, nothing else.
  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    selectAll: () => inputRef.current?.select(),
  }), []);

  return (
    
      {label}
      
    
  );
});

The parent gets two functions. It cannot read the value, it cannot swap the node, and the ref type can declare exactly those two methods instead of HTMLInputElement.

In React 19 ref is a prop

From version 19 ref arrives among the props, so forwardRef is no longer needed. The body of the hook stays identical and the caller does not change a line.

function TextField({ label, ref }) {
  const inputRef = useRef(null);

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    selectAll: () => inputRef.current?.select(),
  }), []);

  return (
    
      {label}
      
    
  );
}

When it is the wrong tool

If the parent only needs to measure the element, a plain ref is enough. If it needs to react to an event, a callback prop reads better. useImperativeHandle adds a layer: use it when the API must be narrower than the node, not to hide a ref nobody should hold.

The command

The package is on npm; the second command prints the resolved version, so the first example does not run on an old major.

npm install react@19 react-dom@19
npm ls react

Live records in the catalogue

Three published records with a narrow API: otp-input focuses one cell, dialog opens and closes without handing out the portal, expandable-tabs switches tab from outside. They are records among the 111,985 components in the catalogue.

Source and licence

React ships under the MIT licence. The reference page on react.dev calls useImperativeHandle an escape hatch and asks you to prefer the declarative route when one exists: that advice is the selection rule, not a footnote.

The limitation

The ref value is reassigned at commit, not during render: a parent that reads ref.current inside its own render sees the previous object, or null on the first pass. The hook does not fix that timing.

Where to continue

The direct comparison between ref and state is in ref DOM vs state; the calling rules for hooks are in rules of hooks; the case where a ref crosses the tree is in portals for modals.