`useImperativeHandle`

Customizes the instance value exposed to parent components through a ref.

Since React 16.8 Spec ↗

Syntax

useImperativeHandle(ref, createHandle, dependencies?)

Parameters

Name	Type	Required	Description
`ref`	`Ref`	Yes	The ref forwarded from the parent (the second argument of forwardRef, or a ref prop in React 19).
`createHandle`	`function`	Yes	Function returning the handle object to expose.
`dependencies`	`array`	No	Reactive values; the handle is recreated when any change.

Returns

undefined — useImperativeHandle returns nothing.

Examples

const Input = forwardRef(function Input(props, ref) {
  const inputRef = useRef(null);
  useImperativeHandle(ref, () => ({
    focus() { inputRef.current.focus(); },
  }), []);
  return <input ref={inputRef} />;
});

Notes

Use it to expose a limited imperative API instead of the raw DOM node. Prefer declarative props; reserve imperative handles for focus, scroll, or media controls. The exposed object should be a stable, minimal surface.