Skip to content
Tutorials Center
My learning

Topics

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.

JSX
<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.

Hydrating with and without the prop

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.

The safer pattern: render in an effect

Syntax

JSX
<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 useId for ids, useSyncExternalStore with 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 window during render.
  • Client-only apps (created with createRoot) never hydrate, so the prop is irrelevant there.