I get hydration warning about data-mantine-color-scheme attribute, what does it mean?

Example hydration warning

Minimal Next.js code that has this warning (Next.js used as an example, the same logic can be applied to any other framework with server-side rendering):

// app/layout.tsx
import { ColorSchemeScript, MantineProvider } from '@mantine/core';

export default function RootLayout({ children }: { children: any }) {
  return (
    <html lang="en">
      <head>
        <ColorSchemeScript />
        <link rel="shortcut icon" href="/favicon.svg" />
        <meta
          name="viewport"
          content="minimum-scale=1, initial-scale=1, width=device-width, user-scalable=no"
        />
      </head>
      <body>
        <MantineProvider>{children}</MantineProvider>
      </body>
    </html>
  );
}

Why do I get hydration warning?

To fully understand this hydration warning, let's break down how server-side rendering works in React in general (Next.js, React Router, etc.):

1. User navigates to the page in the browser.
2. The server renders the page and sends html code to the client.
3. The HTML code is parsed by the browser and rendered on the screen (at this point, JavaScript has not been executed yet; the user has only HTML code).
4. JavaScript code is loaded and executed on the client.
5. Hydration process starts: React compares server-rendered HTML with client-rendered HTML and tries to match them. If server-rendered HTML does not match client-rendered HTML, React will re-render the component on the client and show a warning in the console (like the one above).

Hydration mismatch errors can happen in two cases:

1. Server-rendered HTML does not match client-rendered HTML
2. Some code is executed on the client before React hydration starts and changes the HTML generated by the server

In the example above, the ColorSchemeScript component is used to change the data-mantine-color-scheme attribute on the <html /> element before hydration, which causes the mismatch. The ColorSchemeScript component executes the following JavaScript code:

try {
  var _colorScheme = window.localStorage.getItem("mantine-color-scheme-value");
  var colorScheme = _colorScheme === "light" || _colorScheme === "dark" || _colorScheme === "auto" ? _colorScheme : "light";
  var computedColorScheme = colorScheme !== "auto" ? colorScheme : window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
  document.documentElement.setAttribute("data-mantine-color-scheme", computedColorScheme);
} catch (e) {}

This code is executed on the client before React hydration starts, which changes the HTML generated by the server and causes the warning.

How to fix hydration warning?

To fix the hydration warning, spread mantineHtmlProps on the <html /> element:

// app/layout.tsx
import { ColorSchemeScript, MantineProvider, mantineHtmlProps } from '@mantine/core';

export default function RootLayout({ children }: { children: any }) {
  return (
    <html lang="en" {...mantineHtmlProps}>
      <head>
        <ColorSchemeScript />
        <link rel="shortcut icon" href="/favicon.svg" />
        <meta
          name="viewport"
          content="minimum-scale=1, initial-scale=1, width=device-width, user-scalable=no"
        />
      </head>
      <body>
        <MantineProvider>{children}</MantineProvider>
      </body>
    </html>
  );
}

What is mantineHtmlProps?

mantineHtmlProps is an object with just two properties:

export const mantineHtmlProps = {
  suppressHydrationWarning: true,
  'data-mantine-color-scheme': 'light',
};

• suppressHydrationWarning is used to disable hydration warning for the <html /> element
• data-mantine-color-scheme is used to set the default color scheme for the app when JavaScript is disabled; it is overridden by the ColorSchemeScript component on the client before hydration

Does hydration warning indicate a problem?

No, in this case, the hydration warning is expected and does not indicate a problem with the app: the data-mantine-color-scheme attribute is changed before hydration to prevent flash of inaccurate color scheme.

How suppressHydrationWarning works?

suppressHydrationWarning is a special attribute that React uses to suppress hydration warnings for a specific element. It does not disable hydration warnings for the whole app, only for the element with this attribute (usually the <html /> element only).