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.