From 37ada544c16b63ec168eac01a7715fa2c295a002 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 11:49:28 -0400
Subject: [PATCH 1/6] [18] Update ReactDOMClient docs

---
 beta/src/pages/apis/reactdom.md     |  4 +--
 content/docs/reference-react-dom.md | 42 ++++++++++++++---------------
 2 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/beta/src/pages/apis/reactdom.md b/beta/src/pages/apis/reactdom.md
index ad610a194ad..51062587aa6 100644
--- a/beta/src/pages/apis/reactdom.md
+++ b/beta/src/pages/apis/reactdom.md
@@ -22,10 +22,10 @@ npm install react-dom
 
 ```js
 // Importing a specific API:
-import { render } from 'react-dom';
+import { createRoot } from 'react-dom/client';
 
 // Importing all APIs together:
-import * as ReactDOM from 'react';
+import * as ReactDOMClient from 'react-dom/client';
 ```
 
 </PackageImport>
diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index ac36022d6b4..2d6866e95e9 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -1,16 +1,16 @@
 ---
 id: react-dom
-title: ReactDOM
+title: ReactDOMClient
 layout: docs
 category: Reference
 permalink: docs/react-dom.html
 ---
 
-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')`.
+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 * as ReactDOMClient from 'react-dom/client'`. If you use ES5 with npm, you can write `var ReactDOMClient = require('react-dom/client')`.
 
 ## Overview {#overview}
 
-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.
+The `react-dom/client` package provides DOM client-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. Most of your components should not need to use this module.
 
 - [`createRoot()`](#createroot)
 - [`hydrateRoot()`](#hydrateroot)
@@ -37,13 +37,13 @@ React supports all popular browsers, including Internet Explorer 9 and above, al
 ### `createRoot()` {#createroot}
 
 ```javascript
-ReactDOM.createRoot(container[, options]);
+ReactDOMClient.createRoot(container[, options]);
 ```
 
 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`:
 
 ```javascript
-const root = ReactDOM.createRoot(container);
+const root = ReactDOMClient.createRoot(container);
 root.render(element);
 ```
 
@@ -55,25 +55,25 @@ root.unmount();
 
 > Note:
 >
-> `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.
+> `ReactDOMClient.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.
 >
-> `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.
+> `ReactDOMClient.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.
 >
-> Using `ReactDOM.createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
+> Using `ReactDOMClient.createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
 
 * * *
 
 ### `hydrateRoot()` {#hydrateroot}
 
 ```javascript
-ReactDOM.hydrateRoot(element, container[, options])
+ReactDOMClient.hydrateRoot(element, container[, options])
 ```
 
 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.
 
-`hydrateRoot` accepts two optional callbacks as options:
-- `onDeleted`: callback called when content is deleted.
-- `onHydrated`: callback called after hydration completes.
+`hydrateRoot` accepts two options:
+- `onRecoverableError`: optional callback called when React automatically recovers from errors during hydration.
+- `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.
 
 
 > Note
@@ -85,14 +85,14 @@ Same as [`createRoot()`](#createroot), but is used to hydrate a container whose
 ### `createPortal()` {#createportal}
 
 ```javascript
-ReactDOM.createPortal(child, container)
+ReactDOMClient.createPortal(child, container)
 ```
 
 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).
 ## Legacy Reference
 ### `render()` {#render}
 ```javascript
-ReactDOM.render(element, container[, callback])
+ReactDOMClient.render(element, container[, callback])
 ```
 
 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)).
@@ -103,22 +103,22 @@ If the optional callback is provided, it will be executed after the component is
 
 > Note:
 >
-> `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.
+> `ReactDOMClient.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.
 >
-> `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.
+> `ReactDOMClient.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.
 >
-> `ReactDOM.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
+> `ReactDOMClient.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
 > 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
 > [callback ref](/docs/refs-and-the-dom.html#callback-refs) to the root element.
 >
-> Using `ReactDOM.render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
+> Using `ReactDOMClient.render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
 
 * * *
 
 ### `hydrate()` {#hydrate}
 
 ```javascript
-ReactDOM.hydrate(element, container[, callback])
+ReactDOMClient.hydrate(element, container[, callback])
 ```
 
 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.
@@ -136,7 +136,7 @@ Remember to be mindful of user experience on slow connections. The JavaScript co
 ### `unmountComponentAtNode()` {#unmountcomponentatnode}
 
 ```javascript
-ReactDOM.unmountComponentAtNode(container)
+ReactDOMClient.unmountComponentAtNode(container)
 ```
 
 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 +150,7 @@ Remove a mounted React component from the DOM and clean up its event handlers an
 > `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)
 
 ```javascript
-ReactDOM.findDOMNode(component)
+ReactDOMClient.findDOMNode(component)
 ```
 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.**
 

From e5042dadd2c6271bdd0beab77bee01dc8d5d03ab Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 11:52:15 -0400
Subject: [PATCH 2/6] Remove ReactDOMClient where it's obvious

---
 content/docs/reference-react-dom.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index 2d6866e95e9..48ee5e6d43b 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -55,11 +55,11 @@ root.unmount();
 
 > Note:
 >
-> `ReactDOMClient.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.
+> `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.
 >
-> `ReactDOMClient.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.
+> `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.
 >
-> Using `ReactDOMClient.createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
+> Using `createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
 
 * * *
 
@@ -103,15 +103,15 @@ If the optional callback is provided, it will be executed after the component is
 
 > Note:
 >
-> `ReactDOMClient.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.
+> `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.
 >
-> `ReactDOMClient.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.
+> `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.
 >
-> `ReactDOMClient.render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
+> `render()` currently returns a reference to the root `ReactComponent` instance. However, using this return value is legacy
 > 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
 > [callback ref](/docs/refs-and-the-dom.html#callback-refs) to the root element.
 >
-> Using `ReactDOMClient.render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
+> Using `render()` to hydrate a server-rendered container is deprecated. Use [`hydrateRoot()`](#hydrateroot) instead.
 
 * * *
 

From a7e5c6b91afdbfb51194a54fa303367ff1e05ac7 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 11:55:34 -0400
Subject: [PATCH 3/6] Update browser message

---
 content/docs/reference-react-dom.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index 48ee5e6d43b..d2e0ec725f7 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -26,7 +26,7 @@ The `react-dom/client` package provides DOM client-specific methods that can be
 
 ### Browser Support {#browser-support}
 
-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.
+React supports all modern browsers, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older versions.
 
 > Note
 >

From ef9e6112096fa89774bb0550553278ed431514f3 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 11:57:27 -0400
Subject: [PATCH 4/6] Update browser message note

---
 content/docs/reference-react-dom.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index d2e0ec725f7..726790ae0fe 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -30,7 +30,7 @@ React supports all modern browsers, although [some polyfills are required](/docs
 
 > Note
 >
-> 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.
+> 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.
 
 ## Reference {#reference}
 

From aa6e638e0a101e3b588b2df7cf9ae69d1ac5fbf8 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 12:31:48 -0400
Subject: [PATCH 5/6] Update based on feedback

---
 content/docs/reference-react-dom.md | 52 ++++++++++++++++++++---------
 1 file changed, 37 insertions(+), 15 deletions(-)

diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index 726790ae0fe..0778fe1e7ae 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -1,24 +1,42 @@
 ---
 id: react-dom
-title: ReactDOMClient
+title: ReactDOM
 layout: docs
 category: Reference
 permalink: docs/react-dom.html
 ---
 
-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 * as ReactDOMClient from 'react-dom/client'`. If you use ES5 with npm, you can write `var ReactDOMClient = require('react-dom/client')`.
+The `react-dom` package provides DOM-specific methods that can be used on the client and server.
+
+```js
+import * as ReactDOM from 'react-dom';
+
+// If you use ES5 with npm, you can write
+var ReactDOM = require('react-dom');
+```
+
+Starting in React 18, `react-dom/client` provides methods specific to the client:
+
+```js
+import * as ReactDOM from 'react-dom/client';
+
+// If you use ES5 with npm, you can write
+var ReactDOM = require('react-dom/client');
+```
 
 ## Overview {#overview}
 
-The `react-dom/client` package provides DOM client-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. Most of your components should not need to use this module.
+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.
 
 - [`createRoot()`](#createroot)
 - [`hydrateRoot()`](#hydrateroot)
-- [`createPortal()`](#createportal)
 
+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.
+- [`createPortal()`](#createportal)
+- 
 > Note
-> 
-> 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)):
+>
+> These `react-dom` 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)):
 >- [`render()`](#render)
 >- [`hydrate()`](#hydrate)
 >- [`findDOMNode()`](#finddomnode)
@@ -37,16 +55,20 @@ React supports all modern browsers, although [some polyfills are required](/docs
 ### `createRoot()` {#createroot}
 
 ```javascript
-ReactDOMClient.createRoot(container[, options]);
+createRoot(container[, options]);
 ```
 
 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`:
 
 ```javascript
-const root = ReactDOMClient.createRoot(container);
+const root = createRoot(container);
 root.render(element);
 ```
 
+`createRoot` accepts two options:
+- `onRecoverableError`: optional callback called when React automatically recovers from errors.
+- `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.
+
 The root can also be unmounted with `unmount`:
 
 ```javascript
@@ -66,13 +88,13 @@ root.unmount();
 ### `hydrateRoot()` {#hydrateroot}
 
 ```javascript
-ReactDOMClient.hydrateRoot(element, container[, options])
+hydrateRoot(element, container[, options])
 ```
 
 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.
 
 `hydrateRoot` accepts two options:
-- `onRecoverableError`: optional callback called when React automatically recovers from errors during hydration.
+- `onRecoverableError`: optional callback called when React automatically recovers from errors.
 - `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.
 
 
@@ -85,14 +107,14 @@ Same as [`createRoot()`](#createroot), but is used to hydrate a container whose
 ### `createPortal()` {#createportal}
 
 ```javascript
-ReactDOMClient.createPortal(child, container)
+createPortal(child, container)
 ```
 
 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).
 ## Legacy Reference
 ### `render()` {#render}
 ```javascript
-ReactDOMClient.render(element, container[, callback])
+render(element, container[, callback])
 ```
 
 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)).
@@ -118,7 +140,7 @@ If the optional callback is provided, it will be executed after the component is
 ### `hydrate()` {#hydrate}
 
 ```javascript
-ReactDOMClient.hydrate(element, container[, callback])
+hydrate(element, container[, callback])
 ```
 
 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.
@@ -136,7 +158,7 @@ Remember to be mindful of user experience on slow connections. The JavaScript co
 ### `unmountComponentAtNode()` {#unmountcomponentatnode}
 
 ```javascript
-ReactDOMClient.unmountComponentAtNode(container)
+unmountComponentAtNode(container)
 ```
 
 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 +172,7 @@ Remove a mounted React component from the DOM and clean up its event handlers an
 > `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)
 
 ```javascript
-ReactDOMClient.findDOMNode(component)
+findDOMNode(component)
 ```
 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.**
 

From 4af8c795e2cc29832d06a882357e116a6fdfae09 Mon Sep 17 00:00:00 2001
From: Rick Hanlon <rickhanlonii@gmail.com>
Date: Thu, 17 Mar 2022 13:45:03 -0400
Subject: [PATCH 6/6] Add react-dom/client docs

---
 content/docs/nav.yml                       |   2 +
 content/docs/reference-react-dom-client.md |  86 ++++++++++++++++++
 content/docs/reference-react-dom.md        | 100 ++++++---------------
 3 files changed, 114 insertions(+), 74 deletions(-)
 create mode 100644 content/docs/reference-react-dom-client.md

diff --git a/content/docs/nav.yml b/content/docs/nav.yml
index dbedc5f5f38..d0acf873b96 100644
--- a/content/docs/nav.yml
+++ b/content/docs/nav.yml
@@ -92,6 +92,8 @@
           title: React.Component
     - id: react-dom
       title: ReactDOM
+    - id: react-dom-client
+      title: ReactDOMClient
     - id: react-dom-server
       title: ReactDOMServer
     - id: dom-elements
diff --git a/content/docs/reference-react-dom-client.md b/content/docs/reference-react-dom-client.md
new file mode 100644
index 00000000000..dfd4bcbd526
--- /dev/null
+++ b/content/docs/reference-react-dom-client.md
@@ -0,0 +1,86 @@
+---
+id: react-dom-client
+title: ReactDOMClient
+layout: docs
+category: Reference
+permalink: docs/react-dom-client.html
+---
+
+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.
+
+```js
+import * as ReactDOM from 'react-dom/client';
+```
+
+If you use ES5 with npm, you can write:
+
+```js
+var ReactDOM = require('react-dom/client');
+```
+
+## Overview {#overview}
+
+The following methods can be used in client environments:
+
+- [`createRoot()`](#createroot)
+- [`hydrateRoot()`](#hydrateroot)
+
+### Browser Support {#browser-support}
+
+React supports all modern browsers, although [some polyfills are required](/docs/javascript-environment-requirements.html) for older versions.
+
+> Note
+>
+> 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.
+
+## Reference {#reference}
+
+### `createRoot()` {#createroot}
+
+```javascript
+createRoot(container[, options]);
+```
+
+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`:
+
+```javascript
+const root = createRoot(container);
+root.render(element);
+```
+
+`createRoot` accepts two options:
+- `onRecoverableError`: optional callback called when React automatically recovers from errors.
+- `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.
+
+The root can also be unmounted with `unmount`:
+
+```javascript
+root.unmount();
+```
+
+> Note:
+>
+> `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.
+>
+> `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.
+>
+> Using `createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
+
+* * *
+
+### `hydrateRoot()` {#hydrateroot}
+
+```javascript
+hydrateRoot(element, container[, options])
+```
+
+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.
+
+`hydrateRoot` accepts two options:
+- `onRecoverableError`: optional callback called when React automatically recovers from errors.
+- `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.
+
+
+> Note
+> 
+> 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.
diff --git a/content/docs/reference-react-dom.md b/content/docs/reference-react-dom.md
index 0778fe1e7ae..e6e1c55175c 100644
--- a/content/docs/reference-react-dom.md
+++ b/content/docs/reference-react-dom.md
@@ -6,41 +6,37 @@ category: Reference
 permalink: docs/react-dom.html
 ---
 
-The `react-dom` package provides DOM-specific methods that can be used on the client and server.
+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.
 
 ```js
 import * as ReactDOM from 'react-dom';
-
-// If you use ES5 with npm, you can write
-var ReactDOM = require('react-dom');
 ```
 
-Starting in React 18, `react-dom/client` provides methods specific to the client:
+If you use ES5 with npm, you can write:
 
 ```js
-import * as ReactDOM from 'react-dom/client';
-
-// If you use ES5 with npm, you can write
-var ReactDOM = require('react-dom/client');
+var ReactDOM = require('react-dom');
 ```
 
+The `react-dom` package also provides modules specific to client and server apps:
+- [`react-dom/client`](/docs/react-dom-client.html)
+- [`react-dom/server`](/docs/react-dom-server.html)
+
 ## Overview {#overview}
 
-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.
+The `react-dom` package exports these methods:
+- [`createPortal()`](#createportal)
 
-- [`createRoot()`](#createroot)
-- [`hydrateRoot()`](#hydrateroot)
 
-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.
-- [`createPortal()`](#createportal)
-- 
-> Note
->
-> These `react-dom` 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)):
->- [`render()`](#render)
->- [`hydrate()`](#hydrate)
->- [`findDOMNode()`](#finddomnode)
->- [`unmountComponentAtNode()`](#unmountcomponentatnode)
+These `react-dom` methods are also exported, but are considered legacy:
+- [`render()`](#render)
+- [`hydrate()`](#hydrate)
+- [`findDOMNode()`](#finddomnode)
+- [`unmountComponentAtNode()`](#unmountcomponentatnode)
+
+> Note: 
+> 
+> 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)).
 
 ### Browser Support {#browser-support}
 
@@ -52,58 +48,6 @@ React supports all modern browsers, although [some polyfills are required](/docs
 
 ## Reference {#reference}
 
-### `createRoot()` {#createroot}
-
-```javascript
-createRoot(container[, options]);
-```
-
-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`:
-
-```javascript
-const root = createRoot(container);
-root.render(element);
-```
-
-`createRoot` accepts two options:
-- `onRecoverableError`: optional callback called when React automatically recovers from errors.
-- `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.
-
-The root can also be unmounted with `unmount`:
-
-```javascript
-root.unmount();
-```
-
-> Note:
->
-> `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.
->
-> `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.
->
-> Using `createRoot()` to hydrate a server-rendered container is not supported. Use [`hydrateRoot()`](#hydrateroot) instead.
-
-* * *
-
-### `hydrateRoot()` {#hydrateroot}
-
-```javascript
-hydrateRoot(element, container[, options])
-```
-
-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.
-
-`hydrateRoot` accepts two options:
-- `onRecoverableError`: optional callback called when React automatically recovers from errors.
-- `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.
-
-
-> Note
-> 
-> 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.
-
-* * *
-
 ### `createPortal()` {#createportal}
 
 ```javascript
@@ -117,6 +61,10 @@ Creates a portal. Portals provide a way to [render children into a DOM node that
 render(element, container[, callback])
 ```
 
+> Note:
+>
+> `render` has been replaced with `createRoot` in React 18. See [createRoot](/docs/react-dom-client.html#createroot) for more info.
+
 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)).
 
 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.
@@ -143,6 +91,10 @@ If the optional callback is provided, it will be executed after the component is
 hydrate(element, container[, callback])
 ```
 
+> Note:
+>
+> `hydrate` has been replaced with `hydrateRoot` in React 18. See [hydrateRoot](/docs/react-dom-client.html#hydrateroot) for more info.
+
 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.
 
 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.