Deprecated

This API will be removed in a future major version of React.

In React 18, hydrate was replaced by hydrateRoot. Using hydrate in React 18 will warn that your app will behave as if it’s running React 17. Learn more here.

hydrate lets you display React components inside a browser DOM node whose HTML content was previously generated by react-dom/server in React 17 and below.

hydrate(reactNode, domNode, callback?)

Reference

hydrate(reactNode, domNode, callback?)

Call hydrate in React 17 and below to “attach” React to existing HTML that was already rendered by React in a server environment.

import { hydrate } from 'react-dom';

hydrate(reactNode, domNode);

React will attach to the HTML that exists inside the domNode, and take over managing the DOM inside it. An app fully built with React will usually only have one hydrate call with its root component.

See more examples below.

Parameters

  • reactNode: The “React node” used to render the existing HTML. This will usually be a piece of JSX like <App /> which was rendered with a ReactDOM Server method such as renderToString(<App />) in React 17.

  • domNode: A DOM element that was rendered as the root element on the server.

  • optional: callback: A function. If passed, React will call it after your component is hydrated.

Returns

hydrate returns null.

Caveats

  • hydrate expects the rendered content to be identical with the server-rendered content. React can patch up differences in text content, but you should treat mismatches as bugs and fix them.
  • In development mode, React warns about mismatches during hydration. There are no guarantees that attribute differences will be patched up in case of mismatches. This is important for performance reasons because in most apps, mismatches are rare, and so validating all markup would be prohibitively expensive.
  • You’ll likely have only one hydrate call in your app. If you use a framework, it might do this call for you.
  • If your app is client-rendered with no HTML rendered already, using hydrate() is not supported. Use render() (for React 17 and below) or createRoot() (for React 18+) instead.

Usage

Call hydrate to attach a React component into a server-rendered browser DOM node.

import { hydrate } from 'react-dom';

hydrate(<App />, document.getElementById('root'));

Using hydrate() to render a client-only app (an app without server-rendered HTML) is not supported. Use render() (in React 17 and below) or createRoot() (in React 18+) instead.

Hydrating server-rendered HTML

In React, “hydration” is how React “attaches” to existing HTML that was already rendered by React in a server environment. During hydration, React will attempt to attach event listeners to the existing markup and take over rendering the app on the client.

In apps fully built with React, you will usually only hydrate one “root”, once at startup for your entire app.