useImperativeHandle: Expose a Custom Ref API
useImperativeHandle exposes a custom API via a ref, letting a parent call specific methods on a child. Instead of exposing an entire DOM node, you can provide a handle with methods like reset() or focus().
Why it exists
Sometimes a parent component needs to tell a child component to do something, like focus an input or reset a form. Standard refs give the parent full access to the child's DOM node, which breaks encapsulation. useImperativeHandle was created to solve this by letting the child expose a limited, intentional API instead.
The mental model
Think of it like a remote control for your component. Instead of handing someone the entire TV (the raw DOM node), you give them a remote with just a few buttons like power and volumeUp (your custom methods). The parent can use the remote but can't open up the TV and start rewiring its internals.
How it works
The hook's signature is useImperativeHandle(ref, createHandle, [dependencies]). You call it inside a child component. The ref is the one passed down from the parent. The createHandle function returns an object containing the methods you want to expose, like { focus: () => internalInputRef.current.focus() }. This object becomes the value of parentRef.current. The optional dependency array re-creates the handle if any of its values change. Since React 19, ref is a standard prop; in older versions, this required using forwardRef.
When to use it
Use it sparingly for imperative actions that are hard to model declaratively with props. Good use cases include triggering a focus() method on a wrapped input, controlling a video player with play() and pause() methods, or triggering a complex animation. It is an escape hatch for when you must issue a command.
When not to use it
Do not use it for anything that can be controlled with state and props. For example, to show or hide a component, pass an isOpen prop instead of creating a show() method. Using it to manage state from the parent is an anti-pattern that leads to confusing, hard-to-debug code by breaking the top-down data flow.
One canonical example
A FancyInput component wraps a standard <input>. A parent form needs to focus this input when a button is clicked. The FancyInput component uses an internal ref for the <input> element and uses useImperativeHandle to expose only one method: focus. The parent can then call myInputRef.current.focus() to focus the input without ever getting access to the underlying <input> DOM node itself.
Interview question
Which scenario best illustrates the primary purpose of useImperativeHandle?
- a.A child component needs to receive and process all props passed down from its parent in a declarative manner.
- b.A parent component needs to directly access and modify the child's internal state variables.
- c.A parent component needs to call a specific method on a child, like focus() or reset(), without exposing the child's entire DOM node.Correct
- d.A child component needs to trigger a re-render of its parent when its internal data changes.
Why? this is the answer
Option C is correct because useImperativeHandle allows a child to expose a limited, intentional API (like specific methods) to a parent via a ref, preventing the parent from accessing the child's full internal DOM or state. Option B describes an anti-pattern that useImperativeHandle is designed to prevent, as it breaks encapsulation and top-down data flow.
Just read this? Test yourself on what you have been reading.
Read the original → react.dev
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on react — each one lists the topics its interview covers.
See open roles