You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `react-dom/client` package provides client-specific methods used for initializing an app on the client. Most of your components should not need to use this module.
10
+
11
+
```js
12
+
import*asReactDOMfrom'react-dom/client';
13
+
```
14
+
15
+
If you use ES5 with npm, you can write:
16
+
17
+
```js
18
+
var ReactDOM =require('react-dom/client');
19
+
```
20
+
21
+
## Overview {#overview}
22
+
23
+
The following methods can be used in client environments:
24
+
25
+
-[`createRoot()`](#createroot)
26
+
-[`hydrateRoot()`](#hydrateroot)
27
+
28
+
### Browser Support {#browser-support}
29
+
30
+
React supports all modern browsers, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older versions.
31
+
32
+
> Note
33
+
>
34
+
> We do not support older browsers that don't support ES5 methods or microtasks such as Internet Explorer. You may find that your apps do work in older browsers if polyfills such as [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) are included in the page, but you're on your own if you choose to take this path.
35
+
36
+
## Reference {#reference}
37
+
38
+
### `createRoot()` {#createroot}
39
+
40
+
```javascript
41
+
createRoot(container[, options]);
42
+
```
43
+
44
+
Create a React root for the supplied `container` and return the root. The root can be used to render a React element into the DOM with `render`:
45
+
46
+
```javascript
47
+
constroot=createRoot(container);
48
+
root.render(element);
49
+
```
50
+
51
+
`createRoot` accepts two options:
52
+
-`onRecoverableError`: optional callback called when React automatically recovers from errors.
53
+
-`identifierPrefix`: optional prefix React uses for ids generated by `React.useId`. Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix used on the server.
54
+
55
+
The root can also be unmounted with `unmount`:
56
+
57
+
```javascript
58
+
root.unmount();
59
+
```
60
+
61
+
> Note:
62
+
>
63
+
> `createRoot()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when render is called. Later calls use React’s DOM diffing algorithm for efficient updates.
64
+
>
65
+
> `createRoot()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
66
+
>
67
+
> Using `createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
68
+
69
+
* * *
70
+
71
+
### `hydrateRoot()` {#hydrateroot}
72
+
73
+
```javascript
74
+
hydrateRoot(element, container[, options])
75
+
```
76
+
77
+
Same as [`createRoot()`](#createroot), but is used to hydrate a container whose HTML contents were rendered by [`ReactDOMServer`](/docs/react-dom-server.html). React will attempt to attach event listeners to the existing markup.
78
+
79
+
`hydrateRoot` accepts two options:
80
+
-`onRecoverableError`: optional callback called when React automatically recovers from errors.
81
+
-`identifierPrefix`: optional prefix React uses for ids generated by `React.useId`. Useful to avoid conflicts when using multiple roots on the same page. Must be the same prefix used on the server.
82
+
83
+
84
+
> Note
85
+
>
86
+
> React expects that the rendered content is identical between the server and the client. It can patch up differences in text content, but you should treat mismatches as bugs and fix them. In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
Copy file name to clipboardExpand all lines: content/docs/reference-react-dom.md
+42-68
Original file line number
Diff line number
Diff line change
@@ -6,95 +6,65 @@ category: Reference
6
6
permalink: docs/react-dom.html
7
7
---
8
8
9
-
If you load React from a `<script>` tag, these top-level APIs are available on the `ReactDOM` global. If you use ES6 with npm, you can write `import ReactDOM from 'react-dom'`. If you use ES5 with npm, you can write `var ReactDOM = require('react-dom')`.
9
+
The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside the React model if you need to.
10
10
11
-
## Overview {#overview}
12
-
13
-
The `react-dom` package provides DOM-specific methods that can be used at the top level of your app and as an escape hatch to get outside of the React model if you need to. Most of your components should not need to use this module.
14
-
15
-
-[`createRoot()`](#createroot)
16
-
-[`hydrateRoot()`](#hydrateroot)
17
-
-[`createPortal()`](#createportal)
18
-
19
-
> Note
20
-
>
21
-
> These methods are considered legacy. Both `render` and `hydrate` will warn that your app will behave as if it's running React 17 (learn more [here](https://reactjs.org/link/switch-to-createroot)):
React supports all popular browsers, including Internet Explorer 9 and above, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older browsers such as IE 9 and IE 10.
30
-
31
-
> Note
32
-
>
33
-
> We don't support older browsers that don't support ES5 methods, but you may find that your apps do work in older browsers if polyfills such as [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) are included in the page. You're on your own if you choose to take this path.
34
-
35
-
## Reference {#reference}
36
-
37
-
### `createRoot()` {#createroot}
38
-
39
-
```javascript
40
-
ReactDOM.createRoot(container[, options]);
11
+
```js
12
+
import*asReactDOMfrom'react-dom';
41
13
```
42
14
43
-
Create a React root for the supplied `container` and return the root. The root can be used to render a React element into the DOM with `render`:
15
+
If you use ES5 with npm, you can write:
44
16
45
-
```javascript
46
-
constroot=ReactDOM.createRoot(container);
47
-
root.render(element);
17
+
```js
18
+
var ReactDOM =require('react-dom');
48
19
```
49
20
50
-
The root can also be unmounted with `unmount`:
51
-
52
-
```javascript
53
-
root.unmount();
54
-
```
21
+
The `react-dom` package also provides modules specific to client and server apps:
> `ReactDOM.createRoot()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when render is called. Later calls use React’s DOM diffing algorithm for efficient updates.
59
-
>
60
-
> `ReactDOM.createRoot()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
61
-
>
62
-
> Using `ReactDOM.createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
Same as [`createRoot()`](#createroot), but is used to hydrate a container whose HTML contents were rendered by [`ReactDOMServer`](/docs/react-dom-server.html). React will attempt to attach event listeners to the existing markup.
37
+
> Note:
38
+
>
39
+
> Both `render` and `hydrate` have been replaced with new [client methods](/docs/react-dom-client.html) in React 18. These methods will warn that your app will behave as if it's running React 17 (learn more [here](https://reactjs.org/link/switch-to-createroot)).
73
40
74
-
`hydrateRoot` accepts two optional callbacks as options:
75
-
-`onDeleted`: callback called when content is deleted.
76
-
-`onHydrated`: callback called after hydration completes.
41
+
### Browser Support {#browser-support}
77
42
43
+
React supports all modern browsers, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older versions.
78
44
79
45
> Note
80
-
>
81
-
> React expects that the rendered content is identical between the server and the client. It can patch up differences in text content, but you should treat mismatches as bugs and fix them. In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
46
+
>
47
+
> We do not support older browsers that don't support ES5 methods or microtasks such as Internet Explorer. You may find that your apps do work in older browsers if polyfills such as [es5-shim and es5-sham](https://github.com/es-shims/es5-shim) are included in the page, but you're on your own if you choose to take this path.
82
48
83
-
* * *
49
+
## Reference {#reference}
84
50
85
51
### `createPortal()` {#createportal}
86
52
87
53
```javascript
88
-
ReactDOM.createPortal(child, container)
54
+
createPortal(child, container)
89
55
```
90
56
91
57
Creates a portal. Portals provide a way to [render children into a DOM node that exists outside the hierarchy of the DOM component](/docs/portals.html).
92
58
## Legacy Reference
93
59
### `render()` {#render}
94
60
```javascript
95
-
ReactDOM.render(element, container[, callback])
61
+
render(element, container[, callback])
96
62
```
97
63
64
+
> Note:
65
+
>
66
+
> `render` has been replaced with `createRoot` in React 18. See [createRoot](/docs/react-dom-client.html#createroot) for more info.
67
+
98
68
Render a React element into the DOM in the supplied `container` and return a [reference](/docs/more-about-refs.html) to the component (or returns `null` for [stateless components](/docs/components-and-props.html#function-and-class-components)).
99
69
100
70
If the React element was previously rendered into `container`, this will perform an update on it and only mutate the DOM as necessary to reflect the latest React element.
@@ -103,24 +73,28 @@ If the optional callback is provided, it will be executed after the component is
103
73
104
74
> Note:
105
75
>
106
-
> `ReactDOM.render()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.
76
+
> `render()` controls the contents of the container node you pass in. Any existing DOM elements inside are replaced when first called. Later calls use React’s DOM diffing algorithm for efficient updates.
107
77
>
108
-
> `ReactDOM.render()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
78
+
> `render()` does not modify the container node (only modifies the children of the container). It may be possible to insert a component to an existing DOM node without overwriting the existing children.
109
79
>
110
-
> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
80
+
> `render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
111
81
> and should be avoided because future versions of React may render components asynchronously in some cases. If you need a reference to the root `ReactComponent` instance, the preferred solution is to attach a
112
82
> [callback ref](/docs/refs-and-the-dom.html#callback-refs) to the root element.
113
83
>
114
-
> Using `ReactDOM.render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
84
+
> Using `render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
115
85
116
86
* * *
117
87
118
88
### `hydrate()` {#hydrate}
119
89
120
90
```javascript
121
-
ReactDOM.hydrate(element, container[, callback])
91
+
hydrate(element, container[, callback])
122
92
```
123
93
94
+
> Note:
95
+
>
96
+
> `hydrate` has been replaced with `hydrateRoot` in React 18. See [hydrateRoot](/docs/react-dom-client.html#hydrateroot) for more info.
97
+
124
98
Same as [`render()`](#render), but is used to hydrate a container whose HTML contents were rendered by [`ReactDOMServer`](/docs/react-dom-server.html). React will attempt to attach event listeners to the existing markup.
125
99
126
100
React expects that the rendered content is identical between the server and the client. It can patch up differences in text content, but you should treat mismatches as bugs and fix them. In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
@@ -136,7 +110,7 @@ Remember to be mindful of user experience on slow connections. The JavaScript co
Remove a mounted React component from the DOM and clean up its event handlers and state. If no component was mounted in the container, calling this function does nothing. Returns `true` if a component was unmounted and `false` if there was no component to unmount.
@@ -150,7 +124,7 @@ Remove a mounted React component from the DOM and clean up its event handlers an
150
124
> `findDOMNode` is an escape hatch used to access the underlying DOM node. In most cases, use of this escape hatch is discouraged because it pierces the component abstraction. [It has been deprecated in `StrictMode`.](/docs/strict-mode.html#warning-about-deprecated-finddomnode-usage)
151
125
152
126
```javascript
153
-
ReactDOM.findDOMNode(component)
127
+
findDOMNode(component)
154
128
```
155
129
If this component has been mounted into the DOM, this returns the corresponding native browser DOM element. This method is useful for reading values out of the DOM, such as form field values and performing DOM measurements. **In most cases, you can attach a ref to the DOM node and avoid using `findDOMNode` at all.**
0 commit comments