How hydration works in Next.js
On the first load in the App Router, the HTML gives users a fast but non-interactive preview before hydration finishes. React then reconciles the markup that arrived from the server with the client-side JavaScript rather than rebuilding the DOM. The RSC Payload is what React uses to line up the Server Component tree with the Client Component tree on the first load.
App developers using Next.js do not call hydrateRoot themselves; the framework makes the call. That API expects the first client render to produce exactly the same content the server rendered, and React treats differences as bugs.
Selective hydration
With streaming, each Suspense boundary hydrates as its own unit, and React prioritizes the part the user is interacting with. Without Suspense boundaries, React hydrates the whole page in a single blocking pass rather than in smaller tasks that yield to the browser. Our Next.js performance optimization guide covers code splitting for heavy pages.
Hydration errors and fixes
Documented causes in Next.js:
Time-dependent render code. Calling the
Date()constructor in render logic causes hydration errors.Invalid HTML nesting. A
ptag inside anotherptag, or adivinside ap, triggers them too.iOS auto-linking. iOS turns phone numbers and emails into links, which causes a mismatch; a
format-detectionmeta tag turns this off.
React warns about hydration mismatches only in development and does not promise that mismatched attributes get fixed. An unfixed mismatch can slow the page down or, in the worst case, attach event handlers to the wrong elements. When it hits a text mismatch, React recovers by client-rendering from the nearest error or Suspense boundary, which the user sees as a flash.
Code that needs browser APIs can run in useEffect, which executes after hydration, so it does not cause a mismatch. For an unavoidable difference such as a timestamp, suppressHydrationWarning silences the mismatch on a single element only; it does not reach child elements.
The Next.js hydration error page has the full list. For related problems, see common Next.js mistakes that hurt Core Web Vitals, and for an app in production that keeps failing, Next.js project rescue.
Sources
- GlossaryNext.js · nextjs.org
- Getting Started: Server and Client ComponentsNext.js · nextjs.org
- hydrateRootReact · react.dev
- Streaming guideNext.js · nextjs.org
- Text content does not match server-rendered HTMLNext.js · nextjs.org
- How to prevent flash before hydrationNext.js · nextjs.org