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.

import './styles.css';
import { hydrate } from 'react-dom';
import App from './App.js';

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

Usually you shouldn’t need to call hydrate again or to call it in more places. From this point on, React will be managing the DOM of your application. To update the UI, your components will use state.

For more information on hydration, see the docs for hydrateRoot.

Suppressing unavoidable hydration mismatch errors

If a single element’s attribute or text content is unavoidably different between the server and the client (for example, a timestamp), you may silence the hydration mismatch warning.

To silence hydration warnings on an element, add suppressHydrationWarning={true}:

export default function App() {
  return (
    <h1 suppressHydrationWarning={true}>
      Current Date: {new Date().toLocaleDateString()}
    </h1>
  );
}

This only works one level deep, and is intended to be an escape hatch. Don’t overuse it. Unless it’s text content, React still won’t attempt to patch it up, so it may remain inconsistent until future updates.

Handling different client and server content

If you intentionally need to render something different on the server and the client, you can do a two-pass rendering. Components that render something different on the client can read a state variable like isClient, which you can set to true in an effect:

import { useState, useEffect } from "react";

export default function App() {
  const [isClient, setIsClient] = useState(false);

  useEffect(() => {
    setIsClient(true);
  }, []);

  return (
    <h1>
      {isClient ? 'Is Client' : 'Is Server'}
    </h1>
  );
}

This way the initial render pass will render the same content as the server, avoiding mismatches, but an additional pass will happen synchronously right after hydration.

Pitfall

This approach makes hydration slower because your components have to render twice. Be mindful of the user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so rendering a different UI immediately after hydration may feel jarring to the user.

PreviousfindDOMNodeNextrender

How do you like these docs?