styled-components styles flash or mismatch after server render in Next.js
Warning: 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.
Fix it fast
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/2Match what you see, then jump to its fix
- 1
No styledComponents key in next.config; class names differ between server and client.The styled-components compiler option is offFix - 2
The page renders unstyled for a moment on first load.No style registry wraps the appFix - 3
The 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
- 1
What does the error look like?
Warning: Prop `className` did not match. Server: "..." Client: "..."Text content does not match server-rendered HTMLA 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.js2Fix
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 devConfirmed by nextjs.org
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 startConfirmed by nextjs.org
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 devConfirmed by nextjs.org
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
Web apps
React hydration failed: the server HTML and the first browser render differ
Text content does not match server-rendered HTML
Hydration fails when the first render in the browser produces different HTML from the HTML the server sent.
5 causes, each with a fixWeb apps
AuthUserPoolException: Auth UserPool not configured in a Next.js app
Auth UserPool not configured
The error means an Amplify Auth call ran before Amplify.configure did.
3 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fix