Expose selected input actions
A parent needs to focus, select, scroll, or clear a child-controlled input without owning its DOM node.
React 19+ · Hook
useImperativeHandle
useImperativeHandle customizes the value exposed through a ref. In React 19, a component can receive ref as a prop and expose a restricted object of imperative methods instead of its underlying DOM node.
How it works
Call this Hook at the top level of a component to replace the usual ref value with a custom handle. The handle factory returns any value, commonly an object of methods. Include every reactive value used by that factory in the dependency list so React can recreate the handle when those values change; in React 19, a function component receives ref as a prop.
Syntax
useImperativeHandle(ref, createHandle, dependencies?)Parameters
| Name | Type | Description |
|---|---|---|
ref | ref | The ref received by the component; this is the ref whose exposed value will be customized. |
createHandle | function | A zero-argument function that returns the value to expose through the ref. |
dependencies | array | Optional inline, constant-length list of all reactive values used by createHandle. |
Returns
undefined
Key points
- It replaces the default ref exposure with a deliberately chosen handle.
- Call it unconditionally at the component’s top level, not inside branches or loops.
- The factory accepts no arguments and returns the complete exposed value.
- The exposed handle is not restricted to an object; it may use any value type.
- A compact methods object is the usual way to provide a narrow imperative API.
- Dependency changes are detected with Object.is semantics.
Common mistakes
- Keep the dependency array inline and fixed-length; it is not a dynamically sized list.
- Do not omit reactive props, state, or component-local variables referenced by the factory.
Example: Expose a restricted input API
import { useImperativeHandle, useRef, useState } from 'react';
function MyInput({ ref }) {
const inputRef = useRef(null);
useImperativeHandle(ref, () => ({
focus() {
inputRef.current?.focus();
},
clear() {
inputRef.current.value = '';
}
}), []);
return <input ref={inputRef} />;
}
export default function App() {
const inputRef = useRef(null);
const [focused, setFocused] = useState(false);
return <>
<MyInput ref={inputRef} />
<button onClick={() => { inputRef.current.focus(); setFocused(true); }}>Focus</button>
<button onClick={() => inputRef.current.clear()}>Clear</button>
{focused && <p>Focused</p>}
</>;
}The child keeps its DOM ref private while exposing only focus and clear methods to the parent.
When to use it
Hide implementation details
A component wraps a complex widget but should reveal only a small command API.
Bridge imperative APIs
A child must provide an imperative operation that cannot be expressed naturally with declarative props.
Publish reactive methods
A ref handle depends on current props or state and must be refreshed when those values change.
Interview questions
QWhat problem does useImperativeHandle solve?
It customizes the value exposed through a ref. The factory returns the handle, which can be any type and is often an object containing a small set of methods.
Follow-up: Why use it instead of exposing a DOM node? A custom handle limits the parent to intentional operations and keeps the DOM implementation private.
QHow should dependencies be specified?
The dependency list contains every reactive value read by the factory, including props, state, and variables or functions declared in the component. React compares dependencies with Object.is and recreates the handle when one changes or when no list is supplied.
Follow-up: What constraint applies to the list? It must have a constant number of entries and be written inline.
QHow is ref received in React 19?
In React 19, ref is available as a prop, so a function component can pass that prop directly to useImperativeHandle. The Hook returns undefined and must be called at the component’s top level.
Follow-up: How would this differ in older React code? Components commonly used forwardRef to receive the ref, but React 19 documents ref as a prop.
Related
useRefforwardRefuseEffectuseLayoutEffect