LLM Best Practices

CSS Modules vs styled-components

Last updated 3 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Use CSS Modules for new React projects and do not adopt styled-components. Its maintainer put the project in maintenance mode in March 2025, saying that for new projects he would not recommend it or most other CSS-in-JS solutions; only occasional bug fixes continue. It also lacks a React Server Components path because it depends on context, so components that use it need "use client".

Comparison

DimensionCSS Modulesstyled-components 6
Project statusPart of bundlers and frameworksMaintenance mode since March 2025
Runtime costNone; static CSS filesJavaScript injects styles
Server ComponentsWorksClient components only
Dynamic valuesCSS custom properties, data-* attributesProp interpolation
ToolingBuilt into Vite, webpack, Next.jsBabel or SWC plugin for SSR naming and ordering
Reading and reviewPlain CSSCSS inside template literals

Pick CSS Modules when

Pick CSS Modules for any new codebase, including Next.js App Router projects.

  • Styles extract to static CSS; nothing runs at paint time.
  • Drive dynamic styling with CSS custom properties set inline or on :root, and with data- attribute selectors rather than class concatenation.
  • Compose with composes or shared custom properties.
import styles from "./Button.module.css";
export const Button = ({ primary, ...p }) => (
  <button className={styles.button} data-primary={primary} {...p} />
);

Keep styled-components when

Keep it only where it already works.

  • A large styled-components v6 codebase with no immediate redesign: freeze new usage and migrate during feature work.
  • Runtime theming from user or tenant data is usually expressible as CSS custom properties; check that first before keeping styled-components for it.

In Next.js, enable compiler.styledComponents in next.config and wrap usage in client components.

Migrate

Migrate file by file. Convert each styled.* to a .module.css rule, replace prop interpolation with data-* attributes or custom properties, and replace ThemeProvider with variables on :root or a theme attribute. Remove the package when no imports remain. For utility-first styling instead, see tailwind-vs-css-modules.

FAQ

Is styled-components deprecated?

styled-components has been in maintenance mode since March 2025, with only occasional bug fixes. Its maintainer does not recommend it for new projects, so use CSS Modules or Tailwind instead.

Does styled-components work with React Server Components?

No; it depends on context, so every component that uses it needs "use client". CSS Modules work in Server Components because they compile to static CSS.

How do I handle dynamic styles without styled-components?

Use CSS custom properties set inline or on :root, and data-* attribute selectors in place of prop interpolation. Replace ThemeProvider with variables on :root or a theme attribute.

Backlinks