Skip to main content

Rendering Hydration Suppress Warning

Source: .agents/references/coding-standard/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md

Metadata​

  • title: Suppress Expected Hydration Mismatches
  • impact: LOW-MEDIUM
  • impactDescription: avoids noisy hydration warnings for known differences
  • tags: rendering, hydration, ssr, nextjs

Content​

Suppress Expected Hydration Mismatches​

In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these expected mismatches, wrap the dynamic text in an element with suppressHydrationWarning to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.

Incorrect (known mismatch warnings):

function Timestamp() {
  return <span>{new Date().toLocaleString()}</span>
}

Correct (suppress expected mismatch only):

function Timestamp() {
  return (
    <span suppressHydrationWarning>
      {new Date().toLocaleString()}
    </span>
  )
}