Skip to content
Tutorials Center
My learning

Topics

React Reference ยท react-dom Client APIs

React createRoot() function

Reference for createRoot from react-dom/client: create a root for a DOM node, render into it, use several roots on one page and avoid common mistakes.

createRoot(domNode, options?) creates a root: the connection between a real DOM element and a React tree. You call it once per container, then use the returned object's render() method to put components inside. It is the entry point of every client-rendered React app since React 18, and the only one in React 19.

The container's existing children are cleared on the first render, and React then owns that subtree. Do not touch it with other libraries or manual DOM edits.

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

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Try it

Your first root
Two independent roots

Syntax

JSX
const root = createRoot(domNode, options?)
Parameter Description
domNode A DOM Element, usually a div. React manages its contents.
options Optional object: identifierPrefix, onUncaughtError, onCaughtError, onRecoverableError. See createRoot options.

Returns a root object with two methods: render(reactNode) and unmount().

Errors

  • Throws Target container is not a DOM element. if domNode is null or not an element (a common mistake when the script runs before the markup, or when the id is misspelled).
  • Passing a container that already has a root logs a warning in development: call root.render() on the existing root instead.

Usage notes

  • Create the root once, outside any component and outside hot code paths. Calling createRoot on every update creates a new root each time and loses all state.
  • render is asynchronous in effect: React schedules the work, so code right after root.render(...) runs before the DOM is filled. Do not read the new DOM immediately; use a ref or an effect inside a component.
  • Pages can have many roots, for example a legacy site adding React widgets one at a time. Roots do not share state or context; use a shared store, or portals within one root, if they must communicate.
  • identifierPrefix keeps useId values unique when several roots are on one page.
  • Container choice: use a dedicated empty element, not document.body. Browser extensions and other scripts modify the body, which can break React.
  • If the container holds server-rendered HTML you want to keep, use hydrateRoot; createRoot discards that markup and renders from scratch.
  • ReactDOM.render was removed in React 19, see ReactDOM.render (removed).
  • createRoot lives in react-dom/client, not react-dom. The old import path fails.