forwardRef & useImperativeHandle

ref is special: forwardRef unwraps it

ref is not a normal prop — React intercepts it before your component ever sees it (in React 18 and earlier, function components silently drop it). React.forwardRef wraps your component so the parent's ref arrives as the second argument: (props, ref) => {'<'}element ref={ref}/{'>'}. useImperativeHandle then narrows what that ref exposes — instead of the raw DOM node, you return a custom API object. The parent calls inputRef.current.focus() and never knows there's an <input> underneath.

piece	role	analogy
`React.forwardRef(fn)`	wraps `fn(props, ref)` so `ref` is forwarded in	the mail slot — passes the parent's ref key into the child's hand
`ref` (2nd arg)	the parent-supplied ref object/callback	the key the parent hands over — the child decides what it unlocks
`useImperativeHandle`	defines `ref.current = factory()` instead of the DOM node	the lobby reception — only the methods you list get announced
`ref.current` (parent side)	the custom API object, NOT the DOM node	the concierge — you ask `.focus()`, never enter the back office

1 · the child you write (edit me)

var FancyInput = React.forwardRef(function (props, ref) {
  // internal ref — the REAL DOM node stays private to the child
  var inputRef = React.useRef();

  // publish a DELIBERATE api: parent never sees inputRef.current
  React.useImperativeHandle(ref, function () {
    return {
      focus: function () { inputRef.current.focus(); },
      clear: function () { inputRef.current.value = ''; },
      getValue: function () { return inputRef.current.value; }
    };
  });

  return (
    <input
      ref={inputRef}
      data-testid="input"
      type="text"
      defaultValue=""
      className="w-full px-3 py-2 bg-[#0d1117] border border-[#30363d] rounded text-[#e6edf3] text-sm outline-none focus:border-[#61dafb]"
      placeholder="Type something, then click Show Value…"
    />
  );
});

function App() {
  // parent's ref — receives the CUSTOM api from useImperativeHandle, not the DOM node
  var inputRef = React.useRef();

  var _React$useState = React.useState('');
  var shown = _React$useState[0];
  var setShown = _React$useState[1];

  return (
    <div className="max-w-sm mx-auto p-5 bg-[#161b22] rounded-xl border border-[#30363d]">
      <h2 className="text-lg font-bold text-[#61dafb] mb-1">FancyInput</h2>
      <p className="text-xs text-[#8b949e] mb-3">
        parent calls inputRef.current.{'{focus, clear, getValue}'} — a custom api, not the raw &lt;input&gt;
      </p>
      <FancyInput ref={inputRef} />
      <div className="flex gap-2 mt-4 flex-wrap">
        <button
          data-testid="focus"
          className="px-4 py-2 bg-[#61dafb] text-[#0d1117] rounded font-bold text-sm hover:opacity-80"
          onClick={function () { if (inputRef.current) inputRef.current.focus(); }}
        >Focus</button>
        <button
          data-testid="clear"
          className="px-4 py-2 bg-[#e74c3c] text-[#0d1117] rounded font-bold text-sm hover:opacity-80"
          onClick={function () { if (inputRef.current) inputRef.current.clear(); }}
        >Clear</button>
        <button
          data-testid="show"
          className="px-4 py-2 bg-transparent border border-[#61dafb] text-[#61dafb] rounded font-bold text-sm hover:opacity-80"
          onClick={function () {
            if (inputRef.current) setShown(inputRef.current.getValue());
          }}
        >Show Value</button>
      </div>
      <p data-testid="display" className="mt-3 text-xs text-[#8b949e]">
        getValue() → <span data-testid="value-text" className="text-[#61dafb]">{shown === '' ? '(empty)' : shown}</span>
      </p>
    </div>
  );
}

createRoot(document.getElementById('root')).render(<App/>);

2 · Babel compiles JSX → element tree

<FancyInput ref={inputRef}/> becomes a call where React routes the ref through forwardRef's wrapper into the render function as the 2nd arg. useImperativeHandle then overwrites ref.current with the factory's return.

// (hit "compile & render" to see Babel's output)

3 · live React (the forwarded ref, proven)

The parent holds inputRef and calls into the child's custom API. The gold-check exercises every method automatically: focus() (asserts the input is document.activeElement), sets the DOM value + getValue() (asserts the parent read it), then clear() (asserts the input was emptied). All four prove the child exposed a deliberate ref API — not its DOM node.

ref api: — · gold: focus → set value → getValue → clear → expect empty

intent → pattern

intent	pattern	why
let parent focus my DOM	`forwardRef((props, ref) => <input ref={ref}/>)`	raw passthrough — parent owns the node directly
expose a curated API	`useImperativeHandle(ref, () => ({'{focus, clear}'}))`	encapsulate internals — parent can't break your markup
limit what the ref shows	return only the methods you want public in the factory	DOM node never leaks — the child stays in control
recompute the handle	`useImperativeHandle(ref, fn, [deps])`	3rd arg = deps array; omit = rebuilt every render (default)
React 19 shortcut	`function Child({ref}) { … }` — ref as a normal prop	no forwardRef wrapper; but the old API still works in 19