Hydration Errors

Why This Error Occurred

While rendering your application, there was a difference between the React tree that was pre-rendered (SSR) and the React tree that rendered during the first render in the Browser (Client).

When css-in-js libraries are not set up for pre-rendering (SSR) it will often lead to a hydration mismatch. In general this means the application has to follow the Next.js example for the library.

This can cause the React tree to be out of sync with the DOM and result in unexpected content/attributes being present.

Possible Ways to Fix It

In general, this issue is caused by using a specific library or application code that is relying on something that could differ between pre-rendering and the browser. An example of this is using window in a component's rendering.

An example:

MyComponent.jsx

const MyComponent = () => {
    // This condition depends on `window`. During the first render of the browser the `color` variable will be different
    const color = typeof window !== "undefined" ? "red" : "blue"


    // As color is passed as a prop there is a mismatch between what was rendered server-side vs what was rendered in the first render
    return <h1 className={`title ${color}`}>Hello World!</h1>
}

How to fix it:

MyComponent.jsx

// In order to prevent the first render from being different you can use `useEffect` which is only executed in the browser and is executed during hydration
import { useEffect, useState } from "react"


const MyComponent = () => {
    // The default value is 'blue', it will be used during pre-rendering and the first render in the browser (hydration)
    const [color, setColor] = useState("blue")


    // During hydration `useEffect` is called. `window` is available in `useEffect`. In this case because we know we're in the browser checking for window is not needed. If you need to read something from window that is fine.
    // By calling `setColor` in `useEffect` a render is triggered after hydrating, this causes the "browser specific" value to be available. In this case 'red'.
    useEffect(() => setColor("red"), [])


    // As color is a state passed as a prop there is no mismatch between what was rendered server-side vs what was rendered in the first render. After useEffect runs the color is set to 'red'
    return <h1 className={`title ${color}`}>Hello World!</h1>
}

Another example:

const IncorrectComponent = () => {
    return (
        <p>
            <div>
                This is not correct and should never be done because the p tag has been abused
            </div>
        </p>
    )
}

How to fix it:

const CorrectComponent = () => {
    return (
        <div>
            <div>
                This is correct and should work because a div is really good for this task.
            </div>
        </div>
    )
}
⚠️
Remember to always pay attention to HTML semantics and rely on best practices to avoid these kinds of errors.

Useful Links

HydrationVactory Next Package