agent-skills/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md

title, impact, impactDescription, tags

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

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>
  )
}