Avoid hydration mismatches

The first client render must match the server HTML.

From next-best-practices, hydration-error.md.

Server HTML vs first render

Pick a snippet, then press New request.

As writtenBad
FixedGood

When a date stops matching

Drag the client offset or the render time.

Server HTMLUTC · en-US
Client first renderMatch

// Render the local value after mount…
const [date, setDate] = useState<string>()
useEffect(() => setDate(new Date(ts).toLocaleDateString()), [ts])

// …or pin locale and zone
new Date(ts).toLocaleDateString('en-US', { timeZone: 'UTC' })

The parser fixes bad nesting

Pick a preset. Red lines are what the parser moved.

React expectsJSX
    Browser builtDiffers

      Why it matters, pros and cons

      Why it matters

      Hydration adopts the server DOM, so the first render must build the same tree.

      Pros

      • No hydration error or client re-render.
      • No flash from server to client text.
      • useId keeps label and aria links intact.

      Cons

      • Mount-only values paint a fallback first; reserve its space.
      • ClientOnly content is missing from the server HTML.
      • Extensions that edit the DOM still cause mismatches.