Made in

Join us for the biggest Figma-to-code launch of the year logo
Talk to Us
Talk to Us










Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required



Get StartedLogin

‹ Back to blog

Web Development

Announcing React Hydration Overlay - Easily Squash Hydration Errors

December 13, 2023

Written By Sami Jaber

TL;DR: go to to install the overlay and debug your hydration mismatch.

Last week, I spent hours debugging a tricky hydration mismatch. I had to:

  • copy the HTML sent over the wire,
  • console.log the HTML generated on the client and copy it,
  • paste both of them into an online diff checker tool.

I got tired of doing this, so I automated it. Hence!

How does it work?

The solution I landed on is fairly rudimentary (like all the best solutions!). The package works in 2 parts:

  • First, you use a plugin to inject hydration-overlay-initializer.js into your app's entry point. This script reads the HTML from the server and stores it, and then listens for hydration errors and stores the page's HTML that exists then.
  • Second, you wrap your app's root in HydrationOverlay, a component that will read the data from the previous step and display it in an overlay.

Currently, only Next.js via a Webpack Plugin. But PRs are more than welcome: what you need is to inject a script into the bundle's entry point, which is fairly straightforward task.

Install the dependnecy with npm (or pnpm, yarn, etc):

npm install

Add the overlay component to the root of your app:

import { HydrationOverlay } from "";

const App = () => {
  return (
      <YourApp />

Add the plugin to your next.config.js

const {
} = require("");

/** @type {import('next').NextConfig} */
const nextConfig = {
  /** your config here */

module.exports = withHydrationOverlay({
   * Optional: `appRootSelector` is the selector for the root element of your app. By default, it is `#__next` which works
   * for Next.js apps with pages directory. If you are using the app directory, you should change this to `main`.
  appRootSelector: "main",

And that's all. Read more in the project readme

As anyone who's had a React hydration mismatch knows, the errors are rather cryptic. In a large page, it becomes extremely difficult to find the mismatched element. While this tool isn't perfect, it automates away a cumbersome manual process that many currently resort to to pin down the exact mismatch.

NOTE: There is a WIP PR to fix this in React, so hopefully there will be a native solution to this problem soon. This plugin will remian handy for all older React versions.

When hydration fails, React will re-render your app on the client-side. It turns out that React renders things slightly differently in SSR VS CSR. The most visible one I've seen is style HTML attributes: whitespace and semi-colons are added in the CSR, and in some cases, the attributes are re-ordered and shorthand attributes are expanded (the most extreme case is all: unset which can seemingly turn into hundreds of properties!). So keep in mind that there will be some false positives when using this plugin. I still firmly believe that it is a net positive to have this tool in your arsenal when debugging hairy issues!

That's it! Go fix your hydration bugs!

Introducing Visual Copilot: a new AI model to convert Figma designs to high quality code in a click.

No setup needed. 100% free. Supports all popular frameworks.

Try Visual Copilot


Hand written text that says "A drag and drop headless CMS?"

Introducing Visual Copilot:

A new AI model to turn Figma designs to high quality code.

Try Visual Copilot

Like our content?

Join Our Newsletter

Continue Reading
Web Development20 MIN
Why React Server Components Are Breaking Builds to Win Tomorrow
WRITTEN BYVishwas Gopinath
February 28, 2024
Web Development20 MIN
The definitive guide to building a drag and drop editable blog with Builder
WRITTEN BYTim Garibaldi
February 26, 2024
Qwik20 MIN
Towards Qwik 2.0: Lighter, Faster, Better
February 9, 2024