createRoot basic signature
createRoot lets you create a root to display React components inside a browser DOM node. Signature: const root = createRoot(domNode, options?)
React · API reference · all subjects
react-dom/createroot
37 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
createRoot domNode parameter
The domNode parameter is a DOM element (from the Web API Element interface). 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.
createRoot return value
createRoot returns an object with two methods: render and unmount.
createRoot with server-rendered app caveat
If your app is server-rendered, using createRoot() is not supported. Use hydrateRoot() instead.
createRoot usage count caveat
You will likely have only one createRoot call in your app. If you use a framework, it might do this call for you.
createRoot vs createPortal for modals and tooltips
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 signature
Call root.render to display a piece of JSX (React node) into the React root's browser DOM node. Signature: root.render(reactNode)
root.render reactNode parameter
The reactNode parameter is 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.
root.render return value
root.render returns undefined.
root.render clears existing HTML
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.
root.render with server-rendered HTML caveat
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.
root.render updates on subsequent calls
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 matching it up with the previously rendered tree. Calling render on the same root again is similar to calling the set function on the root component: React avoids unnecessary DOM updates.
root.render is not fully synchronous
Although rendering is synchronous once it starts, root.render(...) is not. This means code after root.render() may run before any effects (useLayoutEffect, useEffect) of that specific render are fired. This is usually fine and rarely needs adjustment. In rare cases where effect timing matters, you can wrap root.render(...) in flushSync to ensure the initial render runs fully synchronously.
root.unmount signature
Call root.unmount to destroy a rendered tree inside a React root. Signature: root.unmount(). It does not accept any parameters and returns undefined.
root.unmount cleanup behavior
Calling root.unmount will unmount all the components in the root and detach React from the root DOM node, including removing any event handlers or state in the tree.
root.unmount prevents subsequent renders
Once you call root.unmount you cannot call root.render again on the same root. Attempting to call root.render on an unmounted root will throw a Cannot update an unmounted root error. However, you can create a new root for the same DOM node after the previous root for that node has been unmounted.
createRoot basic example
Example showing how to create and render a React app: import { createRoot } from 'react-dom/client'; const root = createRoot(document.getElementById('root')); root.render(<App />);
createRoot multiple roots example
Example showing how to create multiple roots for different parts of a page that uses sprinkles of React: const navRoot = createRoot(document.getElementById('navigation')); navRoot.render(<Navigation />); const commentRoot = createRoot(document.getElementById('comments')); commentRoot.render(<Comments />);
createRoot with error logging example
Example implementing error reporting with onCaughtError, onUncaughtError, and onRecoverableError options: const root = createRoot(container, { onCaughtError: (error, errorInfo) => { reportCaughtError({ error, componentStack: errorInfo.componentStack }); }, onRecoverableError: (error, errorInfo) => { reportRecoverableError({ error, componentStack: errorInfo.componentStack }); }, onUncaughtError: (error, errorInfo) => { reportUncaughtError({ error, componentStack: errorInfo.componentStack }); } }); root.render(<App />);
root.render synchronous timing pitfall
The HTML will not include the rendered component immediately after calling root.render, because while rendering is synchronous once it starts, root.render(...) itself is not. Code after root.render() may run before effects are fired.
createRoot common error: second argument to root.render
A common mistake is to pass the options for createRoot to root.render(...) instead of createRoot(...). root.render only accepts one argument. Pass the root options to createRoot, not to root.render.
createRoot common error: target container not DOM element
The error 'Target container is not a DOM element' means that whatever you are passing to createRoot is not a DOM node. This often happens if document.getElementById returns null because the ID doesn't exist in the document, there is a typo in the ID, or the script tag appears before the DOM node in the HTML.
createRoot common error: function passed instead of component
The error 'Functions are not valid as a React child' means you are passing a function to root.render instead of a component. Pass <Component /> (JSX) instead of Component, or call the function and pass the returned component.
createRoot vs hydrateRoot for server-rendered apps
If your app is server-rendered and includes initial HTML generated by React, use hydrateRoot instead of createRoot. Using createRoot will delete all the server-rendered HTML and re-create all DOM nodes from scratch, which can be slower and reset focus, scroll positions, and user input. hydrateRoot reuses the existing DOM nodes from your HTML and attaches event handlers to them.
createRoot function purpose
createRoot lets you create a root to display React components inside a browser DOM node.
createPortal signature and parameters
createPortal is called with three parameters: children (required), domNode (required), and key (optional). The signature is createPortal(children, domNode, key?). Children can be any renderable React content such as JSX, a Fragment, a string, a number, or an array of these. domNode must be an existing DOM node such as those returned by document.getElementById(). The key is a unique string or number used as the portal's key for ordering.
createPortal return value
createPortal returns a React node that can be included into JSX or returned from a React component. When React encounters it in the render output, it will place the provided children inside the provided domNode.
createPortal usage and physical DOM placement
createPortal renders JSX to a different part of the DOM than where the component is in the React tree. It changes only the physical placement of the DOM node. In every other way, the JSX rendered into a portal acts as a child node of the React component that renders it, including context access and event propagation.
createPortal event propagation follows React tree
Events from portals propagate according to the React tree rather than the DOM tree. If you click inside a portal and the portal is wrapped in a component with an onClick handler, that onClick handler will fire. If this causes issues, either stop event propagation from inside the portal or move the portal itself up in the React tree.
createPortal with different domNode causes recreation
Passing a different DOM node to createPortal during an update will cause the portal content to be recreated.
createPortal example: rendering to document.body
import { createPortal } from 'react-dom'; function MyComponent() { return ( <div style={{ border: '2px solid black' }}> <p>This child is placed in the parent div.</p> {createPortal( <p>This child is placed in the document body.</p>, document.body )} </div> ); } This example shows how createPortal teleports JSX rendered as the second paragraph directly into document.body instead of inside the parent div.
createPortal use case: modal dialogs
Portals can create a modal dialog that floats above the rest of the page, even if the component that renders the dialog is inside a container with overflow: hidden or other styles that would interfere. The modal is not contained within parent JSX elements in the DOM, so it is unaffected by these styles.
createPortal use case: server-rendered pages
Portals can be useful if a React root is only part of a static or server-rendered page not built with React. For example, in a Rails application, portals can create areas of interactivity within static areas such as sidebars. Compared with multiple separate React roots, portals let you treat the app as a single React tree with shared state even though its parts render to different parts of the DOM.
createPortal use case: non-React DOM node management
Portals can manage the content of a DOM node managed outside of React. For example, when integrating with a non-React map widget, you can render React content inside a popup by storing the DOM node returned by the widget and passing it to createPortal.
createPortal accessibility considerations
When using portals, it is important to ensure the app remains accessible. For modals created with portals, you may need to manage keyboard focus so users can move focus in and out of the portal naturally. Follow the WAI-ARIA Modal Authoring Practices guidelines when creating modals.
useId identifierPrefix in createRoot
When rendering multiple independent React applications on a single page, pass identifierPrefix as an option to createRoot or hydrateRoot calls. Every identifier generated with useId will start with the distinct prefix you've specified, ensuring IDs from different apps don't clash.
createRoot API migration from ReactDOM.render
React 18 introduces a new createRoot API. The old pattern was: const container = document.getElementById('root'); ReactDOM.render(<App />, container); The new pattern is: const container = document.getElementById('root'); const root = ReactDOM.createRoot(container); root.render(<App/>);