React Reference ยท Props and Attributes
React suppressHydrationWarning prop
What suppressHydrationWarning does in React, when a hydration mismatch is expected (dates, ids), its one-level limit, and better alternatives.
When the server renders a page, the browser receives HTML first, and React then hydrates it: it attaches event handlers to the existing markup. In development React compares what it would render with what is already there and logs an error if they differ.
Some differences are unavoidable and harmless, such as a "current time" text that is a few seconds older on the client. suppressHydrationWarning tells React that the mismatch in this element's text content or attributes is expected, so it should not complain. It does not fix anything; it only silences the check.
<time suppressHydrationWarning>{new Date().toLocaleTimeString()}</time>
Try it
The example renders to a string (as a server would), puts that HTML into two containers, and hydrates each with a client that renders different text. Only the second one opts out of the check.
A more realistic use is a value that depends on the user's locale or time zone and is only known in the browser. A better design is to render a neutral value first, then update it in an effect, so server and client agree.
Syntax
<element suppressHydrationWarning /> <element suppressHydrationWarning={true} />
| Name | Description |
|---|---|
suppressHydrationWarning |
Boolean. When true, React does not warn about a text or attribute mismatch on this element during hydration. |
Returns: nothing; it is a prop for built-in DOM elements. It has no effect on custom components and no effect outside hydration.
Usage notes
- One level deep. It silences the element it is on, not its children. A mismatch in the element structure (a different tag, an extra child) is still reported.
- React does not patch the text. Where text differs, the server text stays in the DOM until something updates it. The prop hides the warning; it does not synchronise the content.
- Typical uses: timestamps, relative times, ids produced by third-party code, and the
<html>element when a script sets a class (for a theme) before React runs. - Prefer a real fix. Use
useIdfor ids,useSyncExternalStorewith a server snapshot for browser-only values, or an effect that updates state after mount. - Hiding bugs. Do not add it to silence a mismatch you do not understand; the mismatch may point to real differences, such as reading
windowduring render. - Client-only apps (created with
createRoot) never hydrate, so the prop is irrelevant there.