What is hydration in Next js

[falakahmad]

Summary

I can not get this properly every time when I get a hydration error like

Additional information

is there anyone available to answer this question properly ?

Example

hydration error Occured?

[Poliklot]

Hi, @falakahmad !

Hydration in Next.js is basically this:

1. Next.js renders the page on the server and sends ready HTML to the browser.
2. The browser shows that HTML immediately.
3. Then React starts in the browser and attaches interactivity to that already existing HTML.

So the HTML is like the static page, and hydration is the moment when React connects buttons, state, event handlers, etc.

A hydration error happens when the HTML from the server does not match what React renders on the first client render.

For example, this can cause a mismatch:

export default function Page() {
  return <div>{new Date().toLocaleString()}</div>;
}

Why? Because the server may render:

<div>10:00:01</div>

but the browser renders:

<div>10:00:02</div>

React expected the same HTML, but got different text.

Another common example:

export default function ThemeLabel() {
  const theme = localStorage.getItem("theme");

  return <div>{theme}</div>;
}

This is a problem because localStorage only exists in the browser. It is not available during server rendering.

Usually you would move browser-only logic into useEffect:

"use client";

import { useEffect, useState } from "react";

export default function ThemeLabel() {
  const [theme, setTheme] = useState<string | null>(null);

  useEffect(() => {
    setTheme(localStorage.getItem("theme"));
  }, []);

  return <div>{theme}</div>;
}

Common causes are:

• using Date() or Math.random() during render
• using window, document, or localStorage during render
• conditional rendering based on typeof window !== 'undefined'
• invalid HTML nesting, for example <div> inside <p> or <button> inside <button>
• browser extensions, CDN tools, or CSS-in-JS setup changing the HTML

Usually the fix is to make sure the first server render and the first client render produce the same markup.

If something should only happen in the browser, move it to useEffect or render it only after the component mounts.

If you share the exact component/code that causes the hydration error, it will be easier to point out the exact mismatch.

[Itshbhere]

Hydration errors can be confusing at first because the actual issue is usually not the message itself. The error is a symptom that React found a mismatch between what was rendered on the server and what was rendered in the browser.

Step-by-step process to debug hydration errors

Step 1: Understand what hydration means

Hydration is the process where:

1. The server sends pre-rendered HTML
2. The browser loads that HTML
3. React attaches event listeners and builds the client-side application state
4. React expects the client-rendered output to exactly match the server-rendered HTML

If they differ, React throws a hydration error.

---

Step 2: Check the browser console carefully

React often provides hints such as:

• "Text content does not match"
• "Expected server HTML to contain..."
• "Hydration failed because the initial UI does not match"

The message may also point to a component name or DOM element.

For example:

<Text>
  {Date.now()}
</Text>

Server output:

1715000000

Client output:

1715000030

These values differ, causing hydration failure.

---

Step 3: Find values that change during rendering

Search your components for dynamic values such as:

Date.now()
Math.random()
new Date()
crypto.randomUUID()

Bad example:

function Home() {
   return <div>{Date.now()}</div>;
}

Better approach:

function Home() {
   const [time, setTime] = useState("");

   useEffect(() => {
      setTime(Date.now());
   }, []);

   return <div>{time}</div>;
}

useEffect() runs only on the client after hydration.

---

Step 4: Check browser-only APIs

Server-side code cannot access:

window
document
localStorage
sessionStorage
navigator

Problem:

function Home() {
   const theme = localStorage.getItem("theme");

   return <div>{theme}</div>;
}

Server does not have localStorage.

Fix:

function Home() {
   const [theme, setTheme] = useState("");

   useEffect(() => {
      setTheme(localStorage.getItem("theme"));
   }, []);

   return <div>{theme}</div>;
}

---

Step 5: Check conditional rendering

Problem:

function Home() {
   return (
      <div>
         {typeof window !== "undefined"
            ? "Client"
            : "Server"}
      </div>
   );
}

Server renders:

Server

Client renders:

Client

Mismatch occurs.

Better:

function Home() {
   const [mounted, setMounted] = useState(false);

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

   if (!mounted) return null;

   return <div>Client</div>;
}

---

Step 6: Test third-party libraries

Some libraries are not SSR-compatible.

Example:

import SomeLibrary from "some-library";

If the library depends on window internally, hydration may fail.

Try loading it dynamically:

const SomeLibrary = dynamic(
   () => import("./SomeLibrary"),
   { ssr: false }
);

---

Step 7: Inspect the HTML structure

Incorrect HTML nesting can also cause hydration errors.

Bad:

<p>
   <div>Hello</div>
</p>

Correct:

<div>
   <p>Hello</p>
</div>

---

Step 8: Isolate the component

If the app is large:

1. Comment out sections of the page
2. Reload
3. Re-enable components one by one
4. Find the component causing the mismatch

This is often faster than guessing.

---

Quick debugging checklist

✔ Search for Date.now() and Math.random()
✔ Check window and localStorage usage
✔ Check API data consistency
✔ Verify HTML structure
✔ Test third-party packages
✔ Move client-only logic into useEffect()
✔ Isolate components one by one

The easiest way to think about hydration errors is:

Server HTML = Client HTML

If both sides render different output during the first render, hydration errors happen.

[Poliklot]

@Itshbhere @falakahmad

If you are opening these help discussions and accepting answers within a few minutes, please also close them once they are resolved.

Leaving resolved discussions open adds noise and makes it harder for people to find real unresolved issues from users who still need help.