ReactDOMClient

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.

import * as ReactDOM from 'react-dom/client';

If you use ES5 with npm, you can write:

var ReactDOM = require('react-dom/client');

Overview

The following methods can be used in client environments:

• createRoot()
• hydrateRoot()

Browser Support

React supports all modern browsers, although some polyfills are required 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 are included in the page, but you’re on your own if you choose to take this path.

Reference

createRoot()

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:

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:

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() instead.

hydrateRoot()

hydrateRoot(container, element[, options])

Same as createRoot(), but is used to hydrate a container whose HTML contents were rendered by ReactDOMServer. 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.