What is the purpose of the useImperativeHandle hook?

React Beginner Questions - Set 6

It lets a child decide what a forwarded ref exposes — a narrow API instead of the whole DOM node.

Example

import { forwardRef, useImperativeHandle, useRef, useState } from 'react';

const FancyInput = forwardRef(function FancyInput(props, ref) {
  const inputRef = useRef(null);
  const [value, setValue] = useState('');

  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current.focus(),
    clear: () => { setValue(''); inputRef.current.focus(); },
    get length() { return value.length; },
  }), [value]);

  return <input ref={inputRef} value={value} onChange={e => setValue(e.target.value)} />;
});

// Parent
const ref = useRef(null);
ref.current?.clear();   // only these three members exist

What to notice

Without it, a forwarded ref hands the parent a raw DOM node — more power than it needs.
The dependency array rebuilds the handle; omit `value` and `length` freezes at its first value.
Reach for it for focus, scrolling, media playback and animation handles — not for data flow.

← Back to the question list