Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

styled-components styles flash or mismatch after server render in Next.js

ErrorWarning: Prop `className` did not match. Server: "..." Client: "..."

Short answer

This happens when the server-rendered styles and the browser's generated class names differ. Next.js lists an incorrectly configured CSS-in-JS library as a cause. Turn on compiler.styledComponents in next.config, add the style registry with useServerInsertedHTML in the root layout, and use styled-components only in Client Components.

  • Applies to Next.js 15, Next.js 16, styled-components 6
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check that both pieces of the documented setup exist: the compiler flag and the registry component that the root layout uses.

    grep -n "styledComponents" next.config.* ; grep -rln "useServerInsertedHTML" app/ lib/
  2. 2Match what you see, then jump to its fix

    1. 1No styledComponents key in next.config; class names differ between server and client.The styled-components compiler option is offFix
    2. 2The page renders unstyled for a moment on first load.No style registry wraps the appFix
    3. 3The warning stays after the setup is correct, or it comes with a Text content does not match message.A mix of other causes of a server and client differenceFix

What does the error look like?

  • Warning: Prop `className` did not match. Server: "..." Client: "..."
  • Text content does not match server-rendered HTML
  • A flash of unstyled content on first load

Cause 1 of 3

The styled-components compiler option is off

1Check

Next.js documents compiler.styledComponents as the first step for styled-components 6 or newer.

cat next.config.js

2Fix

Enable it in next.config.

// next.config.js
module.exports = {
  compiler: {
    styledComponents: true,
  },
}

3Verify

Restart the dev server and reload the page with the console open.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 3

No style registry wraps the app

1Check

The documented setup collects the rules created during a server render and injects them into the head before the content that uses them. Look for that component in the root layout.

grep -n "Registry" app/layout.*

2Fix

Create a Client Component that collects styles with ServerStyleSheet and injects them through useServerInsertedHTML, and wrap the children of the root layout in it.

// lib/registry.tsx
'use client'
import React, { useState } from 'react'
import { useServerInsertedHTML } from 'next/navigation'
import { ServerStyleSheet, StyleSheetManager } from 'styled-components'

export default function StyledComponentsRegistry({ children }: { children: React.ReactNode }) {
  const [sheet] = useState(() => new ServerStyleSheet())
  useServerInsertedHTML(() => {
    const styles = sheet.getStyleElement()
    sheet.instance.clearTag()
    return <>{styles}</>
  })
  if (typeof window !== 'undefined') return <>{children}</>
  return <StyleSheetManager sheet={sheet.instance}>{children}</StyleSheetManager>
}

// app/layout.tsx: <body><StyledComponentsRegistry>{children}</StyledComponentsRegistry></body>

3Verify

Hard-reload and confirm there is no unstyled flash and no warning.

npm run build && npm run start

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 3

A mix of other causes of a server and client difference

1Check

Next.js lists other hydration causes: invalid HTML nesting such as a div inside a p, rendering that depends on window or on the current time, browser extensions, and a CDN that rewrites the HTML.

grep -rn "typeof window\|Date.now\|new Date()" app/ components/

2Fix

Make the first client render equal the server one. Move browser-only logic into useEffect, and test in a private window with extensions off.

const [isClient, setIsClient] = useState(false)
useEffect(() => setIsClient(true), [])

3Verify

Reload in a private window and read the console.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Follow the official styled-components setup exactly when starting a project, instead of adding it piece by piece.
  • Keep styled components in Client Components, because the library needs client-side React features.
  • Do not branch rendering on typeof window; use an effect for client-only output.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.