createRoot

const root = createRoot(domNode, options?)

• Reference
  • createRoot(domNode, options?)
  • root.render(reactNode)
  • root.unmount()
• Usage
  • Rendering an app fully built with React
  • Rendering a page partially built with React
  • Updating a root component
  • Show a dialog for uncaught errors
  • Displaying Error Boundary errors
  • Displaying a dialog for recoverable errors
• Troubleshooting
  • I’ve created a root, but nothing is displayed
  • I’m getting an error: “You passed a second argument to root.render”
  • I’m getting an error: “Target container is not a DOM element”
  • I’m getting an error: “Functions are not valid as a React child.”
  • My server-rendered HTML gets re-created from scratch

Reference

createRoot(domNode, options?)

Call createRoot to create a React root for displaying content inside a browser DOM element.

import { createRoot } from 'react-dom/client';

const domNode = document.getElementById('root');
const root = createRoot(domNode);

React will create a root for the domNode, and take over managing the DOM inside it. After you’ve created a root, you need to call root.render to display a React component inside of it:

root.render(<App />);

An app fully built with React will usually only have one createRoot call for its root component. A page that uses “sprinkles” of React for parts of the page may have as many separate roots as needed.

See more examples below.

Parameters

• domNode: A DOM element. React will create a root for this DOM element and allow you to call functions on the root, such as render to display rendered React content.

• optional options: An object with options for this React root.

  • Canary only optional onCaughtError: Callback called when React catches an error in an Error Boundary. Called with the error caught by the Error Boundary, and an errorInfo object containing the componentStack.
  • Canary only optional onUncaughtError: Callback called when an error is thrown and not caught by an Error Boundary. Called with the error that was thrown, and an errorInfo object containing the componentStack.
  • optional onRecoverableError: Callback called when React automatically recovers from errors. Called with an error React throws, and an errorInfo object containing the componentStack. Some recoverable errors may include the original error cause as error.cause.
  • optional identifierPrefix: A string prefix React uses for IDs generated by useId. Useful to avoid conflicts when using multiple roots on the same page.

Returns

createRoot returns an object with two methods: render and unmount.

Caveats

• If your app is server-rendered, using createRoot() is not supported. Use hydrateRoot() instead.
• You’ll likely have only one createRoot call in your app. If you use a framework, it might do this call for you.
• When you want to render a piece of JSX in a different part of the DOM tree that isn’t a child of your component (for example, a modal or a tooltip), use createPortal instead of createRoot.

root.render(reactNode)

Call root.render to display a piece of JSX (“React node”) into the React root’s browser DOM node.

root.render(<App />);

React will display <App /> in the root, and take over managing the DOM inside it.

See more examples below.

Parameters

• reactNode: A React node that you want to display. This will usually be a piece of JSX like <App />, but you can also pass a React element constructed with createElement(), a string, a number, null, or undefined.

Returns

root.render returns undefined.

Caveats

• The first time you call root.render, React will clear all the existing HTML content inside the React root before rendering the React component into it.

• If your root’s DOM node contains HTML generated by React on the server or during the build, use hydrateRoot() instead, which attaches the event handlers to the existing HTML.

• If you call render on the same root more than once, React will update the DOM as necessary to reflect the latest JSX you passed. React will decide which parts of the DOM can be reused and which need to be recreated by