Course contentsShow
← React
Lesson 101 of 2,3963. JSX FundamentalsFree lesson

suppressHydrationWarning: The Escape Hatch

When and why to use suppressHydrationWarning to silence intentional server/client content mismatches.

suppressHydrationWarning: The Escape Hatch

You'll learn when to intentionally allow server-rendered HTML to differ from the first client render.

The Hydration Mismatch Problem

When React "hydrates" server-rendered HTML, it expects the initial client render to produce exactly the same output. If there's a mismatch, React throws a warning because it usually indicates a bug.

But sometimes the difference is intentional. The classic example: timestamps. If your server renders <p>Generated at 2:30:15 PM</p> and the client hydrates a few milliseconds later, the time will be slightly different. This isn't a bug—it's reality.

When to Use suppressHydrationWarning

Add suppressHydrationWarning={true} to the specific element that will differ:

<time suppressHydrationWarning>
  {new Date().toLocaleTimeString()}
</time>

This tells React: "I know this content won't match between server and client—trust me, it's intentional."

Think of It Like a Permission Slip

Normally, React is the strict teacher checking that your homework (server HTML) matches your test (client render). suppressHydrationWarning is you saying, "I have a good reason for this difference—please don't mark it wrong."

Use it sparingly. Only apply it to elements where the mismatch is unavoidable (timestamps, random IDs, browser-only features). Don't use it to hide real bugs.

Common Valid Use Cases

  • Current time/date displays
  • User-agent specific content
  • Browser-generated random values
  • Third-party scripts that modify DOM

Key Takeaway: suppressHydrationWarning silences React's hydration mismatch warning for specific elements where server/client differences are intentional, not bugs—use it only when you genuinely need different content on first render.