API Reference
ReactDOM APIs

hydrate

Pitfall

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?)

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. If you want to update the UI, your components can do this by using state.

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

Unavoidable hydration mismatches

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 will make your components slower because they have to render twice, so use it with caution.

Remember to be mindful of user experience on slow connections. The JavaScript code may load significantly later than the initial HTML render, so if you render something different in the client-only pass, the transition can be jarring. However, if executed well, it may be beneficial to render a “shell” of the application on the server, and only show some of the extra widgets on the client. To learn how to do this without getting the markup mismatch issues, refer to the explanation in the previous paragraph.

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.

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 examples above.

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.
PreviousflushSyncNextrender