Skip to content

Remove forwardref from useImperativeHandle docs #7360

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 16, 2024
Merged

Remove forwardref from useImperativeHandle docs #7360

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1416468
fix: remove forwardref from useImperativeHandle docs
SebassNoob Dec 12, 2024
b60d0a1
Make changes more focused
gaearon Dec 16, 2024
19b6aa4
Update useImperativeHandle.md
gaearon Dec 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 36 additions & 32 deletions src/content/reference/react/useImperativeHandle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ useImperativeHandle(ref, createHandle, dependencies?)
Call `useImperativeHandle` at the top level of your component to customize the ref handle it exposes:

```js
import { forwardRef, useImperativeHandle } from 'react';
import { useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
function MyInput({ ref }) {
useImperativeHandle(ref, () => {
return {
// ... your methods ...
Expand All @@ -38,12 +38,18 @@ const MyInput = forwardRef(function MyInput(props, ref) {

#### Parameters {/*parameters*/}

* `ref`: The `ref` you received as the second argument from the [`forwardRef` render function.](/reference/react/forwardRef#render-function)
* `ref`: The `ref` you received as a prop to the `MyInput` 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.

* **optional** `dependencies`: The list of all reactive values referenced inside of the `createHandle` code. Reactive values include props, state, and all the variables and functions declared directly inside your component body. If your linter is [configured for React](/learn/editor-setup#linting), 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 the [`Object.is`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) comparison. If a re-render resulted in a change to some dependency, or if you omitted this argument, your `createHandle` function will re-execute, and the newly created handle will be assigned to the ref.

<Note>

Starting with React 19, [`ref` is available a prop.](/blog/2024/12/05/react-19#ref-as-a-prop) In React 18 and earlier, it was necessary to get the `ref` from [`forwardRef`.](/reference/react/forwardRef)

</Note>

#### Returns {/*returns*/}

`useImperativeHandle` returns `undefined`.
Expand All @@ -54,40 +60,38 @@ const MyInput = forwardRef(function MyInput(props, ref) {

### Exposing a custom ref handle to the parent component {/*exposing-a-custom-ref-handle-to-the-parent-component*/}

By default, components don't expose their DOM nodes to parent components. For example, if you want the parent component of `MyInput` to [have access](/learn/manipulating-the-dom-with-refs) to the `<input>` DOM node, you have to opt in with [`forwardRef`:](/reference/react/forwardRef)

```js {4}
import { forwardRef } from 'react';
To expose a DOM node to the parent element, pass in the `ref` prop to the node.

const MyInput = forwardRef(function MyInput(props, ref) {
return <input {...props} ref={ref} />;
});
```js {2}
function MyInput({ ref }) {
return <input ref={ref} />;
};
```

With the code above, [a ref to `MyInput` will receive the `<input>` DOM node.](/reference/react/forwardRef#exposing-a-dom-node-to-the-parent-component) However, you can expose a custom value instead. To customize the exposed handle, call `useImperativeHandle` at the top level of your component:
With the code above, [a ref to `MyInput` will receive the `<input>` DOM node.](/learn/manipulating-the-dom-with-refs) However, you can expose a custom value instead. To customize the exposed handle, call `useImperativeHandle` at the top level of your component:

```js {4-8}
import { forwardRef, useImperativeHandle } from 'react';
import { useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
function MyInput({ ref }) {
useImperativeHandle(ref, () => {
return {
// ... your methods ...
};
}, []);

return <input {...props} />;
});
return <input />;
};
```

Note that in the code above, the `ref` is no longer forwarded to the `<input>`.
Note that in the code above, the `ref` 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` and `scrollIntoView`. To do this, keep the real browser DOM in a separate ref. Then use `useImperativeHandle` to expose a handle with only the methods that you want the parent component to call:

```js {7-14}
import { forwardRef, useRef, useImperativeHandle } from 'react';
import { useRef, useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
function MyInput({ ref }) {
const inputRef = useRef(null);

useImperativeHandle(ref, () => {
Expand All @@ -101,8 +105,8 @@ const MyInput = forwardRef(function MyInput(props, ref) {
};
}, []);

return <input {...props} ref={inputRef} />;
});
return <input ref={inputRef} />;
};
```

Now, if the parent component gets a ref to `MyInput`, it will be able to call the `focus` and `scrollIntoView` methods on it. However, it will not have full access to the underlying `<input>` DOM node.
Expand Down Expand Up @@ -134,9 +138,9 @@ export default function Form() {
```

```js src/MyInput.js
import { forwardRef, useRef, useImperativeHandle } from 'react';
import { useRef, useImperativeHandle } from 'react';

const MyInput = forwardRef(function MyInput(props, ref) {
function MyInput({ ref, ...props }) {
const inputRef = useRef(null);

useImperativeHandle(ref, () => {
Expand All @@ -151,7 +155,7 @@ const MyInput = forwardRef(function MyInput(props, ref) {
}, []);

return <input {...props} ref={inputRef} />;
});
};

export default MyInput;
```
Expand Down Expand Up @@ -195,11 +199,11 @@ export default function Page() {
```

```js src/Post.js
import { forwardRef, useRef, useImperativeHandle } from 'react';
import { useRef, useImperativeHandle } from 'react';
import CommentList from './CommentList.js';
import AddComment from './AddComment.js';

const Post = forwardRef((props, ref) => {
function Post({ ref }) {
const commentsRef = useRef(null);
const addCommentRef = useRef(null);

Expand All @@ -221,16 +225,16 @@ const Post = forwardRef((props, ref) => {
<AddComment ref={addCommentRef} />
</>
);
});
};

export default Post;
```


```js src/CommentList.js
import { forwardRef, useRef, useImperativeHandle } from 'react';
import { useRef, useImperativeHandle } from 'react';

const CommentList = forwardRef(function CommentList(props, ref) {
function CommentList({ ref }) {
const divRef = useRef(null);

useImperativeHandle(ref, () => {
Expand All @@ -252,17 +256,17 @@ const CommentList = forwardRef(function CommentList(props, ref) {
{comments}
</div>
);
});
}

export default CommentList;
```

```js src/AddComment.js
import { forwardRef, useRef, useImperativeHandle } from 'react';
import { useRef, useImperativeHandle } from 'react';

const AddComment = forwardRef(function AddComment(props, ref) {
function AddComment({ ref }) {
return <input placeholder="Add comment..." ref={ref} />;
});
}

export default AddComment;
```
Expand Down
Loading