createRoot - FiberRoot and HostRoot

The call chain

flowchart TD
  A["createRoot(container, options)<br/>ReactDOMRoot.js"] --> B{isValidContainer?}
  B -- no --> X["throw 'Target container is not a DOM element.'"]
  B -- yes --> C["read options: onUncaughtError, onCaughtError,<br/>onRecoverableError, identifierPrefix, unstable_strictMode"]
  C --> D["createContainer(container, ConcurrentRoot, ...)<br/>ReactFiberReconciler.js"]
  D --> E["createFiberRoot(...)<br/>ReactFiberRoot.js"]
  E --> E1["new FiberRootNode(containerInfo, tag, ...)"]
  E --> E2["createHostRootFiber(tag, isStrictMode)<br/>ReactFiber.js"]
  E --> E3["root.current = hostRootFiber<br/>hostRootFiber.stateNode = root"]
  E --> E4["memoizedState = {element: null, isDehydrated: false, cache}"]
  E --> E5["initializeUpdateQueue(hostRootFiber)"]
  D --> F["registerDefaultIndicator(...)"]
  A --> G["markContainerAsRoot(root.current, container)"]
  A --> H["listenToAllSupportedEvents(container)"]
  A --> I["return new ReactDOMRoot(root)"]

Step 1: validation and options

createRoot lives in react-dom/src/client/ReactDOMRoot.js and is exported through react-dom/client.¹² The first line is isValidContainer, which accepts an Element, a Document or a DocumentFragment. Unless disableCommentsAsDOMContainers is set, it also accepts a comment node with the exact text ' react-mount-point-unstable '.³ Anything else throws Target container is not a DOM element.. In practice this happens when document.getElementById('root') returns null because the script ran before the DOM was parsed.

warnIfReactDOMContainerInDEV then warns in DEV if the container is already marked as a root, i.e. you called createRoot twice on the same container (or on one previously passed to legacy ReactDOM.render).⁴ After that the options are copied into local variables.¹ Two DEV-only checks are worth knowing:

• passing {hydrate: true} warns you to use hydrateRoot,
• passing a JSX element as the options argument (createRoot(el, <App/>), a leftover habit from the old ReactDOM.render(el, container) argument order) prints a helpful error.

concurrentUpdatesByDefaultOverride is hardcoded to false, and the reconciler comment says it is ignored.⁵ Since disableLegacyMode is true in this build, every root is a ConcurrentRoot.⁶

Step 2: createContainer → createFiberRoot

createContainer is a thin adapter. It fixes hydrate = false and initialChildren = null, calls createFiberRoot, and registers the default transition indicator.⁵ hydrateRoot uses the sibling createHydrationContainer. That one does enqueue an initial update right away, because hydration has to match server HTML.⁹

createFiberRoot is where the structure is built:¹⁰

// packages/react-reconciler/src/ReactFiberRoot.js (simplified)
const root = new FiberRootNode(containerInfo, tag, hydrate, identifierPrefix,
                               onUncaughtError, onCaughtError, onRecoverableError, ...);

// Cyclic construction. This cheats the type system right now because stateNode is any.
const uninitializedFiber = createHostRootFiber(tag, isStrictMode);
root.current = uninitializedFiber;
uninitializedFiber.stateNode = root;

const initialCache = createCache();
retainCache(initialCache);
root.pooledCache = initialCache;
retainCache(initialCache);

uninitializedFiber.memoizedState = { element: initialChildren, isDehydrated: hydrate, cache: initialCache };
initializeUpdateQueue(uninitializedFiber);
return root;

FiberRootNode: the fields that matter

The FiberRoot is not a fiber. It is a plain object with a different shape. It holds per-tree state that would be wasteful to keep on every fiber.¹¹

All the lane fields start as NoLanes, and callbackNode starts as null.¹¹ A few of these fields only exist behind feature flags (indicatorLanes, transitionTypes, pendingGestures). The constructor keeps the object shape stable by assigning them conditionally inside the constructor, never later.

createHostRootFiber

// packages/react-reconciler/src/ReactFiber.js (simplified)
export function createHostRootFiber(tag, isStrictMode) {
  let mode = ConcurrentMode;              // disableLegacyMode || tag === ConcurrentRoot
  if (isStrictMode === true) mode |= StrictLegacyMode | StrictEffectsMode;
  if (__DEV__ || (enableProfilerTimer && isDevToolsPresent)) mode |= ProfileMode;
  return createFiber(HostRoot, null, null, mode);
}

¹³ The HostRoot fiber has tag = HostRoot (3), type = null, pendingProps = null and key = null.¹⁴ Its mode bits are inherited by every fiber created below it. Children copy returnFiber.mode when they are created, which is how ConcurrentMode reaches every node. unstable_strictMode: true in createRoot options sets strict mode for the whole tree. A <StrictMode> element only sets the bits from that subtree down (createFiberFromTypeAndProps adds StrictLegacyMode | StrictEffectsMode for REACT_STRICT_MODE_TYPE).¹⁵

Note that no alternate is created yet. The WIP copy of the HostRoot is made lazily by createWorkInProgress(root.current, null) in prepareFreshStack when the first render starts.¹⁶ See Fiber for double buffering.

The HostRoot's state and update queue

The HostRoot is unusual: its "state" is {element, isDehydrated, cache}, and "rendering the root" means processing its update queue to compute a new element. initializeUpdateQueue attaches a class-style queue:¹⁷

fiber.updateQueue = {
  baseState: fiber.memoizedState,      // {element: null, isDehydrated: false, cache}
  firstBaseUpdate: null, lastBaseUpdate: null,
  shared: { pending: null, lanes: NoLanes, hiddenCallbacks: null },
  callbacks: null,
};

This is the same queue structure class components use for this.setState. That is why root.render enqueues an Update with payload: {element} (see root.render). updateHostRoot in beginWork then runs processUpdateQueue and reads nextState.element as the children to reconcile.¹⁸ Hooks use a different queue shape (see Hooks on Mount).

The circular link, drawn

flowchart LR
  subgraph DOM
    C["div#root<br/>__reactContainer$xyz → HostRoot"]
  end
  subgraph Reconciler
    FR["FiberRootNode<br/>containerInfo<br/>current<br/>pendingLanes = 0<br/>callbackNode = null<br/>next = null"]
    HR["HostRoot fiber (tag 3)<br/>stateNode<br/>memoizedState = {element: null}<br/>updateQueue.shared.pending = null<br/>alternate = null<br/>child = null"]
  end
  RD["ReactDOMRoot<br/>_internalRoot"]
  RD -->|_internalRoot| FR
  FR -->|current| HR
  HR -->|stateNode| FR
  FR -->|containerInfo| C
  C -.->|"__reactContainer$..."| HR

After the first commit, HR.child points to the App fiber, and HR.alternate points to the other HostRoot, the one that was the WIP tree. Every commit flips FR.current between the two HostRoot fibers. The stateNode of both points back to the same FR.

Step 3: markContainerAsRoot

node['__reactContainer$' + randomKey] = hostRoot;

randomKey is generated once per copy of react-dom with Math.random().toString(36).slice(2).¹⁹²⁰ It is used for:

• Dev warnings. warnIfReactDOMContainerInDEV uses it (via isContainerMarkedAsRoot) to detect "you already called createRoot on this container".⁴
• Event dispatch. When a native event fires, getClosestInstanceFromNode walks DOM ancestors looking for __reactFiber$ / __reactContainer$ keys to find the target fiber (see Event System).²¹
• Isolation between copies. The random suffix means two copies of React DOM on one page (micro-frontends) never read each other's internal keys.

Note that it stores root.current at creation time. Since the current pointer flips, code that needs the current tree goes through stateNode.current, not this stored fiber.

Step 4: listenToAllSupportedEvents

listenToAllSupportedEvents(rootContainerElement) runs once per container. It is guarded by a listeningMarker property.²² For each native event in allNativeEvents, it attaches a capture-phase listener and, unless the event is in nonDelegatedEvents (things like scroll, load and media events that don't bubble), also a bubble-phase listener on the container. selectionchange gets attached to the document.

Why do this eagerly, before anything renders?

• Delegation at the root, not document. Since React 17, listeners go on the root container. This lets several React roots, or React versions, live on one page, and e.stopPropagation() works the way people expect against non-React handlers on document.
• No per-element listeners. Adding an onClick later costs nothing at the DOM level. The props are just read at dispatch time via __reactProps$.
• Correct priority from the first event. The listener wrapper (createEventListenerWrapperWithPriority) sets ReactDOMSharedInternals.p based on the event type before calling into React. That is how a click handler's setState ends up on SyncLane (see Lanes & Scheduler, setState).

The full mechanics are on Event System.

Step 5: the ReactDOMRoot object

function ReactDOMRoot(internalRoot) { this._internalRoot = internalRoot; }
ReactDOMRoot.prototype.render = function (children) { /* ... */ updateContainer(children, root, null, null); };
ReactDOMRoot.prototype.unmount = function () { /* ... */ updateContainerSync(null, root, null, null); flushSyncWork(); unmarkContainerAsRoot(container); };

²³ The public object is deliberately thin: one field, two prototype methods (ReactDOMHydrationRoot shares them). Points worth noticing:

• render no longer accepts a callback. In DEV, passing one logs "does not support the second callback argument... use useEffect()". Passing the container again logs a similar error.
• unmount is synchronous. It uses updateContainerSync (SyncLane) followed by flushSyncWork(), and in DEV it warns if called during a render. It sets _internalRoot = null first, so a second render after unmount throws Cannot update an unmounted root..

With the React Compiler

Nothing here changes. createRoot, the FiberRoot and the HostRoot fiber are reconciler and renderer code. The compiler only rewrites component bodies and never touches react-dom. The only setup difference you might see is that compiled components call _c(n) on their first render. That allocates the memo cache on their own fiber's update queue, not on the root (see React Compiler).

Summary

createRoot sets the stage and renders nothing. It validates the container, builds a FiberRoot and a HostRoot fiber that point at each other, marks the container, attaches every event listener, and returns a thin ReactDOMRoot. The FiberRoot is the single, un-double-buffered owner of per-tree state (lanes, the scheduled callback, the container). The HostRoot fiber tops the fiber tree, and its class-style update queue is where root.render enqueues an {element} update in the next part.

Key takeaways

• isValidContainer: anything but an Element, Document or DocumentFragment throws Target container is not a DOM element., typically a null from getElementById.
• ConcurrentRoot only: with disableLegacyMode, every root is concurrent and ReactDOM.render is gone, so automatic batching is unconditional.
• createFiberRoot: builds the cycle, root.current is the HostRoot and hostRootFiber.stateNode is the root.
• FiberRootNode: not a fiber, a plain object for per-tree state such as pendingLanes and callbackNode.
• createHostRootFiber: sets mode bits every fiber below inherits; no alternate exists until prepareFreshStack.
• initializeUpdateQueue: the class-component queue shape, so rendering the root means processing it to compute a new element.
• markContainerAsRoot: a randomly suffixed __reactContainer$ key used by DEV warnings, event dispatch and isolation between React copies.
• listenToAllSupportedEvents: eager capture and bubble listeners on the container, so later onClick props cost nothing at the DOM level.
• ReactDOMRoot: one field, two methods; render takes no callback and unmount is synchronous.

← Prev · Index · Next →