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.
import { createRoot } from 'react-dom/client'; const root = createRoot(document.getElementById('root')); root.render(<App />);
Try it
Syntax
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.ifdomNodeisnullor 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
createRooton every update creates a new root each time and loses all state. renderis asynchronous in effect: React schedules the work, so code right afterroot.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.
identifierPrefixkeepsuseIdvalues 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;createRootdiscards that markup and renders from scratch. ReactDOM.renderwas removed in React 19, see ReactDOM.render (removed).createRootlives inreact-dom/client, notreact-dom. The old import path fails.