suppressHydrationWarning Prop
What you'll learn: How to intentionally suppress hydration warnings when server-client mismatches are unavoidable and expected.
Sometimes hydration mismatches are intentional and unavoidable. The classic example is timestamps: the server renders "Generated at 3:45 PM" but by the time the client hydrates milliseconds later, it's now 3:46 PM. React will complain about the mismatch even though it's expected behavior.
For these rare cases, React provides suppressHydrationWarning as an escape hatch.
How It Works
Add suppressHydrationWarning={true} to the specific element that will differ between server and client:
function Timestamp() {
return (
<time suppressHydrationWarning>
{new Date().toLocaleTimeString()}
</time>
);
}
This tells React: "I know this element will mismatch—don't warn me." React will use the server HTML initially, then replace it with the client value after hydration without logging an error.
When to Use It
Only use this for:
- Current timestamps that change between renders
- Timezones that differ server vs client
- Content intentionally personalized post-hydration
Critical rules:
- Apply it to the smallest possible element (the
<time>tag, not a wrapper<div>) - It only suppresses warnings for that one element, not its children
- Never use it to hide bugs—fix actual mismatches with
useEffectpatterns instead
Think of it as a "I meant to do that" flag. It doesn't fix mismatches; it just silences the warning when the mismatch is intentional.
Key Takeaway: suppressHydrationWarning is a last-resort prop for unavoidable, intentional mismatches like timestamps—use it surgically on specific elements, never as a blanket fix for actual hydration bugs.