` cannot be a descendant of `
`" comes from the browser rewriting the HTML, which no prop can hide.
5. **It is on the wrong element.** next-themes changes ``, so the prop belongs on ``, not on `
`.
The first case is the most common:
```tsx title="components/clock.tsx"
"use client";
export function Clock() {
return (
// Does nothing: the text is inside the
, one level down.
{new Date().toLocaleTimeString()}
);
}
```
```tsx title="components/clock.tsx"
"use client";
export function Clock() {
return (
{/* Works: the prop is on the element that holds the text. */}
{new Date().toLocaleTimeString()}
);
}
```
## suppressHydrationWarning: Next.js root layout
The usual place for it in Next.js is `` in the root layout, because theme libraries set a class or `style` there before React hydrates. shadcn/ui's [dark mode guide](https://ui.shadcn.com/docs/dark-mode/next) and next-themes both tell you to add it:
```tsx title="app/layout.tsx"
import type { ReactNode } from "react";
import { ThemeProvider } from "@/components/theme-provider";
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Because it works one level deep, it covers only the attributes of `` itself. A theme toggle that renders a different icon for the current theme still needs its own fix; see [theme hydration errors](https://hydration.jscrate.dev/docs/causes/theme).
## suppressHydrationWarning: React Router root
In React Router's framework mode, `` is rendered by the `Layout` export of `app/root.tsx`. The `Layout` in [React Router's docs](https://reactrouter.com/api/framework-conventions/root.tsx) does not include the prop. Add it only when a script changes `` before hydration, for example to set the theme:
```tsx title="app/root.tsx"
import type { ReactNode } from "react";
import { Links, Meta, Scripts, ScrollRestoration } from "react-router";
export function Layout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
## Can you ignore, disable or hide a hydration error in Next.js?
No. Neither React nor Next.js has a setting that turns hydration errors off for a whole app, and [Next.js's hydration error page](https://nextjs.org/docs/messages/react-hydration-error) offers three fixes: `useEffect`, disabling SSR for a component, and `suppressHydrationWarning` on the element.
There is a reason for that. The message is a symptom: by the time it appears, React 19 has already thrown the server HTML away and rendered the tree again on the client. Hiding the log does not stop the re-render, the lost state or the layout shift. And for attributes, React 19 production builds already stay silent while the wrong value stays on the page.
What you can do instead:
- **Fix the cause.** Each cause has a local fix; [the React hydration error guide](https://hydration.jscrate.dev/docs/guides/react-hydration-error) maps each message to one.
- **Render the part on the client only** with a [client-only component](https://hydration.jscrate.dev/docs/guides/client-only-component) or `next/dynamic` with `ssr: false`.
- **Use `suppressHydrationWarning`** on the one element whose value cannot match.
- **Ignore extension noise in tests,** not in the app: a clean browser profile has no extensions, and hydration-proof has [ignore rules](https://hydration.jscrate.dev/docs/ignoring) for attributes you cannot control.
In a custom React setup, the `onRecoverableError` option of `hydrateRoot` decides how recovered errors are logged. It changes the log, not what React does.
## hydration-proof vs suppressHydrationWarning
They answer different questions. `suppressHydrationWarning` hides a difference from React's warnings. hydration-proof finds differences, including the hidden ones, and tells you what each suppression hides.
| | `suppressHydrationWarning` | hydration-proof |
| --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| What it does | Stops React reporting one element's attribute and text differences | Loads every route and compares the server HTML with the client render |
| Scope | One element, one level deep | Every element on every tested page |
| The page | Keeps the server's value | Unchanged: nothing is added to your app |
| Hidden differences | Invisible from then on | Listed as [HP6001](https://hydration.jscrate.dev/docs/issues/hp6001), for information |
| Structural differences | Not hidden | [HP6002](https://hydration.jscrate.dev/docs/issues/hp6002): the prop cannot hide this |
| A prop with nothing to hide | Not reported | [HP6003](https://hydration.jscrate.dev/docs/issues/hp6003): remove it before it hides a future bug |
The ESLint rule [`audit-suppress-hydration-warning`](https://hydration.jscrate.dev/docs/rules/audit-suppress-hydration-warning) catches the misplaced ones while you type: the prop on an element with child elements, on an element with only static content, or on a component. It accepts `` and `` by default, and it checks Server Components too, because the root layout is one.
## Related
- [Intentional differences and how hydration-proof lists them](https://hydration.jscrate.dev/docs/causes/suppressed)
- [Next-themes and dark mode hydration errors](https://hydration.jscrate.dev/docs/causes/theme)
- [useEffect and two-pass rendering](https://hydration.jscrate.dev/docs/guides/useeffect-two-pass-rendering)
- [Ignoring findings in hydration-proof](https://hydration.jscrate.dev/docs/ignoring)
- [React hydration errors: messages and causes](https://hydration.jscrate.dev/docs/guides/react-hydration-error)