Next.js pre-renders HTML on the server, then React hydrates it on the client to add interactivity; a hydration mismatch occurs when the server and client HTML differ, causing React to warn or fail
Hydration is the process where React takes over the static HTML that was pre-rendered by Next.js on the server and makes it interactive by attaching event handlers and state. Next.js pre-renders every page by default, generating HTML in advance for better performance and SEO. When the browser loads this HTML, it's immediately visible to the user. Then, React's hydration step runs in the background, attaching event listeners and reconciling the component tree with the existing DOM. In Next.js 14+ with the App Router, only Client Components actually hydrate—Server Components are rendered entirely on the server and don't send JavaScript to the client, significantly reducing the amount of hydration work required.
Definition: A hydration mismatch occurs when the HTML generated on the server differs from what React renders during the first render on the client. React expects the initial client render to perfectly match the server HTML to be able to attach event handlers efficiently.
Warning symptoms: The browser console shows warnings like 'Text content did not match server-rendered HTML' and React attempts to recover, but this recovery process can be costly for performance.
Impact: Mismatches force React to discard the server HTML and re-render on the client, causing layout shifts, lost CSS, and degraded user experience.
Browser-only APIs: Using window, localStorage, or document in component rendering without checking if code runs on the server.
Dynamic data without server rendering: Fetching data client-side with useState/useEffect but having no initial server-rendered value.
Time-dependent content: Using Date() or Math.random() directly in render, producing different values on server vs client.
Incorrect HTML nesting: Placing block elements inside <p> tags, nested <a> tags, or other invalid HTML structures.
Browser extensions modifying DOM: Some extensions inject elements or modify content, causing client HTML to differ from server.
CSS Modules with lazy loading: Next.js may fail to include CSS for lazily-loaded components in the initial bundle, causing a flash of unstyled content during hydration.
iOS format detection: iOS automatically converts phone numbers and dates to links, altering the HTML structure.
Next.js provides several tools to help debug hydration issues. The development server shows detailed error messages pointing to the component tree where the mismatch occurs. Using React 18.2+ ensures you get the best hydration mismatch warnings with component stack traces. The Next.js Dev Tools extension can highlight exactly which elements differ. For production debugging, you can compare the server-rendered HTML (view page source) with the client DOM (inspect element) to identify discrepancies. Look for the specific element where the content differs and trace back to its component logic.
- Read the console error carefully: The error message often includes the exact text that mismatched and points to the component.
- Check your component tree: Identify which component contains the mismatched content by looking at the stack trace.
- Compare server and client output: Run a production build locally with next build && next start to test the exact behavior.
- Isolate browser extensions: Test in incognito mode or with extensions disabled to rule out DOM modifications.
- Add suppression strategically: Use suppressHydrationWarning only for intentionally different content like timestamps.
React 18+ introduced selective hydration, allowing you to wrap less important components in Suspense to defer their hydration. This improves perceived performance by prioritizing critical UI. However, selective hydration with CSS Modules can cause Flash of Unstyled Content (FOUC) if Next.js fails to include the CSS in the initial bundle. The component's HTML is correctly server-rendered with the proper class name, but the CSS loads lazily with the component, causing a visual flash when hydration completes. This issue particularly affects Pages Router with React.lazy and Suspense, and forces developers to choose between using CSS Modules or selective hydration benefits.
Use Server Components for data fetching: Prefer async Server Components over client-side data fetching to ensure server and client match.
Wrap dynamic content in useEffect: Any code that accesses browser APIs or uses dynamic data should run in useEffect, not in render.
Check HTML validation: Use tools like the W3C validator to catch invalid nesting patterns.
Disable iOS format detection: Add the meta tag to prevent automatic link creation.
Test with JavaScript disabled: Verify your page renders meaningful content without JS, confirming pre-rendering works.
Use dynamic imports with SSR disabled: For components that must differ on client, import them with next/dynamic and ssr: false.
Hydration mismatch warnings are most helpful with React 18.2.0 or higher. Older React versions may not provide component stack traces or detailed mismatch information, making debugging significantly harder. Next.js recommends keeping React updated to the latest version to benefit from improved error messages and hydration features like selective hydration. The minimum React version for optimal hydration debugging is 18.2.0.