How to fix Warning: Prop `className` did not match. Server: "..." Client: "..." in React

What this error means

This hydration warning occurs when React compares the server-rendered HTML with the client-side React tree and discovers that the `className` prop on a component or element doesn't match between the two environments. During server-side rendering (SSR), React generates HTML on the server and sends it to the browser. When the JavaScript bundle loads on the client, React performs "hydration" - it attaches event listeners and initializes the React component tree by comparing it to the existing server-rendered HTML. If the className values differ, React detects this mismatch and logs a warning. This is particularly common with CSS-in-JS libraries (styled-components, Emotion, JSS) that generate dynamic class names. If the server generates `css-abc123` but the client generates `css-xyz789`, React flags this inconsistency. The mismatch can cause visual flashing, incorrect styles, or accessibility issues.

Typical symptoms

• Console warning showing different className values for server vs client
• Brief flash of unstyled content (FOUC) when page loads
• Components appear with incorrect styles initially, then suddenly update
• Warning appears in development mode but may be silent in production
• Issue occurs specifically with server-side rendered pages (Next.js, Remix, etc.)
• Multiple similar warnings for different components using the same styling library

Common causes

1. CSS-in-JS libraries (styled-components, Emotion, JSS) generating non-deterministic class names between server and client
2. Missing or incorrectly configured babel plugin for styled-components
3. Conditional rendering based on browser-only APIs (window, localStorage) executed during initial render
4. Material-UI components using different class name generators on server vs client
5. Theme values (dark mode, user preferences) initialized differently on server and client
6. Version mismatch between Material-UI or styled-components on server and client bundles
7. Client-side state accessed during initial render before hydration completes
8. Random values, timestamps, or IDs used in className generation
9. CSS modules with different hash generation between build environments

How to fix "Warning: Prop `className` did not match. Server: "..." Client: "...""

Warning: Prop `className` did not match.
Server: "css-abc123 MuiButton-root"
Client: "css-xyz789 MuiButton-root"

npm install --save-dev babel-plugin-styled-components

{
  "plugins": [
    [
      "babel-plugin-styled-components",
      {
        "ssr": true,
        "displayName": true,
        "preprocess": false
      }
    ]
  ]
}

module.exports = {
  compiler: {
    styledComponents: true,
  },
}

import createCache from '@emotion/cache';

export default function createEmotionCache() {
  return createCache({ key: 'css', prepend: true });
}

import { CacheProvider } from '@emotion/react';
import createEmotionCache from '../lib/createEmotionCache';

const clientSideEmotionCache = createEmotionCache();

function MyApp({ Component, emotionCache = clientSideEmotionCache, pageProps }) {
  return (
    <CacheProvider value={emotionCache}>
      <Component {...pageProps} />
    </CacheProvider>
  );
}

import createEmotionServer from '@emotion/server/create-instance';
import createEmotionCache from '../lib/createEmotionCache';

export default class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const cache = createEmotionCache();
    const { extractCriticalToChunks } = createEmotionServer(cache);

    const originalRenderPage = ctx.renderPage;
    ctx.renderPage = () =>
      originalRenderPage({
        enhanceApp: (App) => (props) => <App emotionCache={cache} {...props} />,
      });

    const initialProps = await Document.getInitialProps(ctx);
    const emotionStyles = extractCriticalToChunks(initialProps.html);

    return { ...initialProps, emotionStyles };
  }
}

function ThemeToggle() {
  const isDark = localStorage.getItem('theme') === 'dark';
  return <div className={isDark ? 'dark' : 'light'}>...</div>;
}

function ThemeToggle() {
  const [isDark, setIsDark] = useState(false);

  useEffect(() => {
    setIsDark(localStorage.getItem('theme') === 'dark');
  }, []);

  return <div className={isDark ? 'dark' : 'light'}>...</div>;
}

npm list styled-components
npm list @emotion/react
npm list @mui/material

rm -rf node_modules package-lock.json
npm install

{
  "dependencies": {
    "styled-components": "6.1.8",
    "@emotion/react": "11.11.3"
  }
}

function Timestamp() {
  const [time, setTime] = useState(new Date().toISOString());

  useEffect(() => {
    setTime(new Date().toISOString());
  }, []);

  return (
    <div suppressHydrationWarning>
      {time}
    </div>
  );
}

Advanced notes

Frequently asked questions

What does "Warning: Prop `className` did not match. Server: "..." Client: "..."" mean?

This hydration warning occurs when React compares the server-rendered HTML with the client-side React tree and discovers that the className prop on a component or element doesn't match between the two environments. During server-side rendering (SSR), React generates HTML on the server and sends it to the browser. When the JavaScript bundle loads on the client, React performs "hydration" - it attaches event listeners and initializes the React component tree by comparing it to the existing server-rendered HTML.

How do I fix "Warning: Prop `className` did not match. Server: "..." Client: "...""?

This warning appears during React hydration when the className generated on the server differs from the one generated on the client. Commonly caused by CSS-in-JS libraries like styled-components, Material-UI, or conditional rendering that differs between server and client.

What causes "Warning: Prop `className` did not match. Server: "..." Client: "...""?

CSS-in-JS libraries (styled-components, Emotion, JSS) generating non-deterministic class names between server and client Missing or incorrectly configured babel plugin for styled-components Conditional rendering based on browser-only APIs (window, localStorage) executed during initial render

Is the "Warning: Prop `className` did not match. Server: "..." Client: "..."" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• Async component function detected but component is not async

  How to fix "Async component function detected but component is not async" in React

  MEDIUM

• this.state must be initialized in constructor, not in class body

  Class state must be initialized in constructor

  MEDIUM

• Component should not return undefined, null or false

  Component should not return undefined, null or false

  MEDIUM

• Constructor in class component does not call super(props)

  How to fix "Constructor in class component does not call super(props)" in React

  HIGH

• Failed to resolve import. Does the file exist?

  How to fix "Failed to resolve import" in React

  HIGH

• npm ERR! code ETIMEDOUT npm ERR! network request to https://registry.npmjs.org timed out

  npm registry request timed out

  MEDIUM

Official resources & further reading

• 📚React Official Documentation