React: What is hydration mismatch?

Hydration mismatch is when HTML generated on the server does not match what React expects on the client.

Simple analogy: Imagine you assembled a puzzle according to a picture (server HTML). Then a friend came and rearranged several pieces (client React). You look at the puzzle and don't understand: "I assembled it differently!".

When it occurs:

1. Different data — server got one data, and on the client it is different (for example, different time zone).
   jsxКопировать

   1// BAD: on server 10:00, on client 10:02
   2<p>Current time: {new Date().toString()}</p>

2. Browser APIs — localStorage, navigator, window are not available on the server:
   jsxКопировать

   1// BAD: window does NOT exist on server
   2<p>Screen width: {window.innerWidth}</p>

3. Random values — Math.random(), uuid are different on server and client.

How to fix:

1. suppressHydrationWarning: If the difference is not critical (for example, timer), you can suppress the warning:

1<p suppressHydrationWarning>Time: {new Date().toString()}</p>

2. useEffect — defer render to client:

1function WindowWidth() {
2    const [width, setWidth] = useState(0);  // On server: 0
3    
4    useEffect(() => {
5        setWidth(window.innerWidth);  // On client: real
6    }, []);
7    
8    return <p>Width: {width}</p>;
9}

3. "use client" + dynamic import: In Next.js you can load a component only on the client:

1const ClientComponent = dynamic(() => import('./ClientComponent'), { ssr: false });

Error in console: React will output a warning with text "Hydration failed because the initial UI does not match...". Look in server and client logs for what exactly differs.