createRoot()

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

// Create a root with the specified DOM node
const root = createRoot(domNode);

// Mount a React component
root.render(<App />);

// Unmount the root and destroy the React tree
root.unmount();

Argument / Return Value	Overview
domNode (argument)	The DOM element to use as the mount target for the React tree. Typically obtained with document.getElementById('root').
options (argument, optional)	An optional options object. Pass a function to the onRecoverableError property to receive errors that React recovers from automatically.
root (return value)	Returns a root object with two methods: render() and unmount().
root.render() (method)	Renders the JSX passed as an argument to the DOM. Calling it again on the same root updates only the differences.
root.unmount() (method)	Unmounts the React tree and destroys all event listeners and state.

A basic example of using createRoot() in the entry point (index.js or main.jsx) to mount a React application.

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

// Root component
// This component serves as the entry point for the entire application
function App() {
  return (
    <div>
      <h1>My First React App</h1>
      <p>Mounted with createRoot().</p>
    </div>
  );
}

// Get the <div id="root"></div> on the HTML side
// This node becomes the mount target for the React tree
const domNode = document.getElementById('root');

// Pass the mount target DOM node to createRoot() to create the root
const root = createRoot(domNode);

// Pass the root component to render() to start rendering
// React 18's concurrent rendering (Concurrent Features) becomes enabled
root.render(<App />);

In development environments, it is recommended to wrap with React.StrictMode.

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

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

// Wrapping with StrictMode displays additional warnings about problematic code
// It is automatically disabled in production builds, so using it during development is recommended
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Runtime error when the root node is null

If document.getElementById('root') returns null (wrong ID, script runs too early, etc.), calling createRoot(null) causes a runtime error. Adding a null check before passing the value to createRoot() prevents this.

ng_example.jsx

// NG: No null check
const root = createRoot(document.getElementById('app')); // Returns null if the ID differs from 'root'
root.render(<App />);

ok_example.jsx

// OK: Add a null check
const domNode = document.getElementById('root');
if (!domNode) {
  throw new Error('Mount target DOM node not found.');
}
const root = createRoot(domNode);
root.render(<App />);

Mixing ReactDOM.render() and createRoot()

Using the old ReactDOM.render() in a React 18 project causes console warnings and prevents React 18 concurrent rendering features from being enabled. Unify to createRoot().

ng_example.jsx

// NG: Using the old ReactDOM.render() in a React 18 project
import ReactDOM from 'react-dom';
ReactDOM.render(<App />, document.getElementById('root'));

ok_example.jsx

// OK: Use createRoot()
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(<App />);

Calling root.render() multiple times

Call root.render() on a root created with createRoot() only once during initialization. Updates to components are handled through state and props changes. Unintentionally calling root.render() multiple times causes unnecessary re-renders and degrades performance.

ng_example.jsx

// NG: Calling root.render() multiple times
const root = createRoot(document.getElementById('root'));
root.render(<App />);
root.render(<App />); // Unnecessary re-render

ok_example.jsx

// OK: Initial render only once. Updates are managed via state/props
const root = createRoot(document.getElementById('root'));
root.render(<App />);
// Subsequent updates are managed by state/props inside the App component

createRoot() is a function added in React 18 that replaces the previous ReactDOM.render() as the new way to mount an application. Using createRoot() enables React 18's concurrent rendering (Concurrent Features), unlocking new features such as useTransition() and automatic batching.

The basic usage is to call it once in the entry point file to create the root, then pass the root component to the returned object's render() method. Even if render() is called multiple times on the same root, React efficiently updates only the differences.

If you want to manage only a specific DOM element with React rather than the entire app (such as co-existing with an existing non-React application), you can create multiple roots using multiple createRoot() calls.

Related pages: component / useTransition