Fixing Hydration Errors: A Guide to the 'use client' Directive

'Use Client' Isn't a Dirty Word

It's not a downgrade. It's an architectural boundary.

The 'Uncanny Valley' of UI

• The Glitch — You load a page. For a split second, the button is white, then it snaps to blue.
• The Error — Console screams: 'Hydration failed because the initial UI does not match what was rendered on the server.'

What is Hydration?

[Image of React Hydration process diagram] Turning dry HTML into living React.

• Server Side — React runs on the server and spits out static HTML strings.
• Client Side — Browser loads HTML. Then React loads and attaches event listeners.
• The Rules — The HTML the server sent MUST match exactly what the browser expects.

The Culprit: Browser APIs

• The Mistake — Rendering window.localStorage or new Date() directly in the JSX.
• Why — The Server doesn't have window. The Server's timezone might be UTC, yours is EST.
• Result — Server says 'A'. Client calculates 'B'. React panics.

The Fix: useEffect or use client

• Delaying — Use useEffect to write data after the initial paint. Avoids mismatch.
• Boundary — Mark the component as 'use client' to explicitly opt-out of Server rendering logic.

Component Composition Pattern

• Don't De-optimize — Don't make the entire page a Client Component.
• Leaf Nodes — Push the interactivity down to the buttons and forms (The Leaves). Keep the layout Server (The Trunk).

Summary: Respect the Boundary

Hydration errors are just architecture hints.

Know where your code runs. The Server is for data, the Client is for interactivity.

How do you handle window objects in Next.js?