react-dom

What is react-dom?

The react-dom package provides DOM-specific methods that can be used at the top level of a web app to enable an efficient way of managing DOM elements in response to data changes. It is a companion package to React that facilitates rendering components to the DOM and interacting with the DOM tree.

What are react-dom's main functionalities?

Rendering React Elements

This feature allows you to render a React element into the DOM in the supplied container and return a reference to the component (or returns null for stateless components).

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

Component Lifecycle Management

react-dom manages the lifecycle of components, including mounting, updating, and unmounting components.

class MyComponent extends React.Component {
  componentDidMount() {
    // Code to run when the component is mounted
  }

  componentWillUnmount() {
    // Code to run before the component is unmounted and destroyed
  }
}

Handling Events

react-dom provides a synthetic event system that wraps the native event system, providing a cross-browser interface to native events.

function MyComponent() {
  function handleClick(e) {
    e.preventDefault();
    console.log('The link was clicked.');
  }

  return (
    <a href="#" onClick={handleClick}>
      Click me
    </a>
  );
}

Server-side Rendering

react-dom/server provides methods for rendering components to static markup (typically used on the server) such as renderToString and renderToStaticMarkup.

ReactDOMServer.renderToString(
  <MyComponent />
);

Portals

Portals provide a way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

ReactDOM.createPortal(
  child,
  container
);

Other packages similar to react-dom

preact

Preact is a fast 3kB alternative to React with the same modern API. It provides similar functionalities for rendering UIs but with a smaller footprint, making it a good choice for performance-sensitive applications.

inferno

Inferno is an extremely fast, React-like library for building high-performance user interfaces on both the client and server. It offers a similar component-based UI building experience but focuses on performance optimizations.

vue-server-renderer

This package is part of the Vue ecosystem and provides server-side rendering capabilities similar to react-dom/server. It's used to render Vue components on the server and send the static markup to the client.

README

react-dom

This package serves as the entry point to the DOM and server renderers for React. It is intended to be paired with the generic React package, which is shipped as react to npm.

Installation

npm install react react-dom

Usage

In the browser

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

function App() {
  return <div>Hello World</div>;
}

const root = createRoot(document.getElementById('root'));
root.render(<App />);

On the server

import { renderToPipeableStream } from 'react-dom/server';

function App() {
  return <div>Hello World</div>;
}

function handleRequest(res) {
  // ... in your server handler ...
  const stream = renderToPipeableStream(<App />, {
    onShellReady() {
      res.statusCode = 200;
      res.setHeader('Content-type', 'text/html');
      stream.pipe(res);
    },
    // ...
  });
}

API

react-dom

See https://react.dev/reference/react-dom

react-dom/client

See https://react.dev/reference/react-dom/client

react-dom/server

See https://react.dev/reference/react-dom/server

Changelog

19.1.0 (March 28, 2025)

Owner Stack

An Owner Stack is a string representing the components that are directly responsible for rendering a particular component. You can log Owner Stacks when debugging or use Owner Stacks to enhance error overlays or other development tools. Owner Stacks are only available in development builds. Component Stacks in production are unchanged.

• An Owner Stack is a development-only stack trace that helps identify which components are responsible for rendering a particular component. An Owner Stack is distinct from a Component Stacks, which shows the hierarchy of components leading to an error.
• The captureOwnerStack API is only available in development mode and returns a Owner Stack, if available. The API can be used to enhance error overlays or log component relationships when debugging. #29923, #32353, #30306, #32538, #32529, #32538

React

• Enhanced support for Suspense boundaries to be used anywhere, including the client, server, and during hydration. #32069, #32163, #32224, #32252
• Reduced unnecessary client rendering through improved hydration scheduling #31751
• Increased priority of client rendered Suspense boundaries #31776
• Fixed frozen fallback states by rendering unfinished Suspense boundaries on the client. #31620
• Reduced garbage collection pressure by improving Suspense boundary retries. #31667
• Fixed erroneous “Waiting for Paint” log when the passive effect phase was not delayed #31526
• Fixed a regression causing key warnings for flattened positional children in development mode. #32117
• Updated useId to use valid CSS selectors, changing format from :r123: to «r123». #32001
• Added a dev-only warning for null/undefined created in useEffect, useInsertionEffect, and useLayoutEffect. #32355
• Fixed a bug where dev-only methods were exported in production builds. React.act is no longer available in production builds. #32200
• Improved consistency across prod and dev to improve compatibility with Google Closure Complier and bindings #31808
• Improve passive effect scheduling for consistent task yielding. #31785
• Fixed asserts in React Native when passChildrenWhenCloningPersistedNodes is enabled for OffscreenComponent rendering. #32528
• Fixed component name resolution for Portal #32640
• Added support for beforetoggle and toggle events on the dialog element. #32479 #32479

React DOM

• Fixed double warning when the href attribute is an empty string #31783
• Fixed an edge case where getHoistableRoot() didn’t work properly when the container was a Document #32321
• Removed support for using HTML comments (e.g. <!-- -->) as a DOM container. #32250
• Added support for <script> and <template> tags to be nested within <select> tags. #31837
• Fixed responsive images to be preloaded as HTML instead of headers #32445

use-sync-external-store

• Added exports field to package.json for use-sync-external-store to support various entrypoints. #25231

React Server Components

• Added unstable_prerender, a new experimental API for prerendering React Server Components on the server #31724
• Fixed an issue where streams would hang when receiving new chunks after a global error #31840, #31851
• Fixed an issue where pending chunks were counted twice. #31833
• Added support for streaming in edge environments #31852
• Added support for sending custom error names from a server so that they are available in the client for console replaying. #32116
• Updated the server component wire format to remove IDs for hints and console.log because they have no return value #31671
• Exposed registerServerReference in client builds to handle server references in different environments. #32534
• Added react-server-dom-parcel package which integrates Server Components with the Parcel bundler #31725, #32132, #31799, #32294, #31741