useImperativeHandle

useImperativeHandle(ref,createHandle,dependencies?)

• Reference
  • useImperativeHandle(ref, createHandle, dependencies?)
• Usage
  • Exposing a custom ref handle to the parent component
  • Exposing your own imperative methods

Reference

useImperativeHandle(ref, createHandle, dependencies?)

CalluseImperativeHandle at the top level of your component to customize the ref handle it exposes:

import{useImperativeHandle}from'react';

functionMyInput({ref}){
useImperativeHandle(ref,()=>{
return{
// ... your methods ...
};
},[]);
// ...

See more examples below.

Parameters

• ref: Theref you received as a prop to theMyInput component.

• createHandle: A function that takes no arguments and returns the ref handle you want to expose. That ref handle can have any type. Usually, you will return an object with the methods you want to expose.

• optionaldependencies: The list of all reactive values referenced inside of thecreateHandle code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter isconfigured for React, it will verify that every reactive value is correctly specified as a dependency. The list of dependencies must have a constant number of items and be written inline like[dep1, dep2, dep3]. React will compare each dependency with its previous value using theObject.is comparison. If a re-render resulted in a change to some dependency, or if you omitted this argument, yourcreateHandle function will re-execute, and the newly created handle will be assigned to the ref.

Returns

useImperativeHandle returnsundefined.

Usage

Exposing a custom ref handle to the parent component

To expose a DOM node to the parent element, pass in theref prop to the node.

functionMyInput({ref}){
return<inputref={ref}/>;
};

With the code above,a ref toMyInput will receive the<input> DOM node. However, you can expose a custom value instead. To customize the exposed handle, calluseImperativeHandle at the top level of your component:

import{useImperativeHandle}from'react';

functionMyInput({ref}){
useImperativeHandle(ref,()=>{
return{
// ... your methods ...
};
},[]);

return<input/>;
};

Note that in the code above, theref is no longer passed to the<input>.

For example, suppose you don’t want to expose the entire<input> DOM node, but you want to expose two of its methods:focus andscrollIntoView. To do this, keep the real browser DOM in a separate ref. Then useuseImperativeHandle to expose a handle with only the methods that you want the parent component to call:

import{useRef,useImperativeHandle}from'react';

functionMyInput({ref}){
constinputRef =useRef(null);

useImperativeHandle(ref,()=>{
return{
focus(){
inputRef.current.focus();
},
scrollIntoView(){
inputRef.current.scrollIntoView();
},
};
},[]);

return<inputref={inputRef}/>;
};

Now, if the parent component gets a ref toMyInput, it will be able to call thefocus andscrollIntoView methods on it. However, it will not have full access to the underlying<input> DOM node.

Exposing your own imperative methods

The methods you expose via an imperative handle don’t have to match the DOM methods exactly. For example, thisPost component exposes ascrollAndFocusAddComment method via an imperative handle. This lets the parentPage scroll the list of commentsand focus the input field when you click the button: