React DOM

react-dom is the platform-specific renderer that pairs with the react package to turn React element trees into real DOM nodes in the browser or an HTML stream on the server. It exposes createRoot and hydrateRoot for client-side mounting and hydration, plus a family of server APIs — renderToPipeableStream, renderToReadableStream, and the legacy renderToString — for rendering React on Node, edge, and other JavaScript runtimes.

Maintained inside the same monorepo as react by the React core team at Meta, react-dom ships in lockstep with each React release and implements the reconciler’s host-config contract for the DOM: committing fiber updates to real elements, managing the synthetic event system, and handling hydration mismatches. Nearly every production React app — from bare Vite setups to Next.js and Remix — depends on it as the bridge between React’s virtual tree and the actual page.

What You Get

• createRoot and hydrateRoot for mounting and hydrating client-side React trees
• Streaming server-render APIs (renderToPipeableStream, renderToReadableStream) for Node, edge, and other runtimes
• A synthetic event system that normalizes DOM events across browsers with delegated, pooled dispatch
• Resource-hint APIs (preconnect, preload, preinit) for coordinating asset loading with rendering
• Legacy renderToString/renderToStaticMarkup APIs for non-streaming SSR use cases

Common Use Cases

• Mounting a client-rendered single-page React app into a DOM container
• Hydrating server-rendered HTML on the client so React can attach event listeners without a full re-render
• Streaming HTML from a Node or edge server as React components resolve, for fast time-to-first-byte SSR
• Generating static HTML strings at build time for static site generators

Under The Hood

Architecture

react-dom is the DOM-target implementation of React’s platform-agnostic renderer, split across two packages in the same monorepo: react-dom (the public entry points in index.js and client.js, re-exporting from src/client/ReactDOMClient.js and src/shared/ReactDOM.js) and react-dom-bindings (the DOM-specific implementation in src/client, src/events, and src/server). createRoot and hydrateRoot, defined in src/client/ReactDOMRoot.js, validate the target container via react-dom-bindings/src/client/ReactDOMContainer.js and hand off to react-reconciler, which drives the actual fiber-tree diffing and commit work — react-dom itself supplies the reconciler’s DOM ‘host config’ (how to create, update, and remove real nodes) rather than reimplementing diffing. Server rendering is a separate code path: ReactDOMFizzServerNode.js, ReactDOMFizzServerEdge.js, and per-runtime entry points like react-dom-server.node.js and react-dom-server.edge.js implement React’s Fizz streaming renderer, each producing a runtime-appropriate stream (Node Writable vs. Web ReadableStream) from the same component tree. Event handling is centralized in react-dom-bindings/src/events, which delegates listeners at the root and dispatches synthetic events through a plugin system rather than attaching handlers per DOM node.

Tech Stack

The codebase is authored in Flow-typed JavaScript (flow-bin ^0.317.0) rather than TypeScript, compiled through a custom Babel pipeline (babel.config.js, babel.config-ts.js) and bundled per release channel with Rollup via scripts/rollup/build-all-release-channels.js. It’s a Yarn workspace monorepo (packages/*) with react-dom as one of dozens of interdependent packages (react, react-reconciler, react-dom-bindings, scheduler); react-dom’s only runtime dependency is scheduler, with react itself required as a matching peerDependency. Tests run on Jest 29, and the repo additionally builds an experimental Rust-based React Compiler (the top-level compiler/ directory) that ships as a separate package rather than being part of react-dom directly.

Code Quality

Testing is extensive and colocated: over 130 -test.js files sit alongside implementation files across src/client, src/events, src/server, and src/test-utils, covering hydration mismatches, event delegation, and streaming edge cases with React’s internal fixture-based test harness. Code favors small, single-purpose modules (ReactDOMRoot.js, for example, is 380 lines and handles only root creation/options, not rendering itself) with Flow type annotations on public option objects (CreateRootOptions, HydrateRootOptions) documenting every callback’s error/error-info shape. Naming is consistent and DOM-specific (ReactDOM prefix throughout), and feature flags (shared/ReactFeatureFlags, e.g. disableCommentsAsDOMContainers) gate experimental behavior instead of branching on ad hoc conditionals, keeping stable code paths readable.

API Design The public surface is deliberately small and split by concern: react-dom/client for browser mounting (createRoot, hydrateRoot), react-dom/server (and its runtime-specific siblings server.node, server.edge, server.browser) for SSR, and root-level exports like createPortal, flushSync, and the preload/preinit/preconnect resource hints. This subpath-based export design, driven by package.json ‘exports’ conditions keyed on react-server/workerd/bun/node/edge-light, lets bundlers pull in only the runtime-appropriate implementation without dead code — unusually sophisticated for an npm package’s exports map. Getting started requires minimal boilerplate, just one createRoot() call and one .render(), though the breadth of server APIs (five different render-to-stream variants) means picking the right one for your deployment target is the main learning cost, offset by consistent naming and centralized docs at react.dev/reference/react-dom.