CSS Modules

Introduction

In the last lesson you saw that plain CSS files share one global namespace — meaning two components can accidentally define the same class name and silently override each other's styles. CSS Modules solve this exact problem by automatically scoping every class name to the specific component that imports it.

This lesson goes deep on CSS Modules: how the file naming convention works, how imported class names map onto generated, unique names, and how to combine multiple classes together conditionally, a very common need once you start building interactive UI.

What are CSS Modules?

A CSS Module is simply a regular CSS file with one special naming convention: it ends in .module.css instead of just .css. Most modern React build tools (Vite, Create React App, Next.js) recognize this suffix automatically and process the file differently than an ordinary stylesheet.

Instead of injecting the class names exactly as written, the build tool rewrites every class name in the file into something guaranteed to be unique across your entire app — often by appending a hash, like .card_a8f3e. Because the generated name is unique, it can never collide with a class of the same name defined in another component's module file.

Creating a Module File

To create a CSS Module for a Button component, name the file Button.module.css and place it alongside Button.jsx. Inside it, write ordinary CSS rules exactly as you always would.

.button {
  padding: 10px 20px;
  border: none;
  border-radius: 6px;
  font-weight: 600;
  cursor: pointer;
}

.primary {
  background-color: #4f46e5;
  color: white;
}

.secondary {
  background-color: #e5e7eb;
  color: #111827;
}

Nothing here looks different from a normal CSS file. The scoping magic happens entirely when this file is imported into a component.

Using Scoped Class Names

When you import a .module.css file, you do not get individual class name strings — you get a single styles object whose keys match your class names and whose values are the generated, scoped names. You then apply them using styles.className in the className attribute.

import styles from './Button.module.css';

function Button({ children }) {
  return (
    <button className={styles.button}>
      {children}
    </button>
  );
}

export default Button;

<button class="Button_button__a8f3e">Click Me</button>

How Scoping Actually Works

Behind the scenes, the build tool parses your .module.css file, renames every selector to something unique — typically combining the file name, the original class name, and a short hash — and generates a mapping object. That mapping object is exactly what gets imported as styles in your component.

Button.module.css is loaded
        ↓
Every class selector is renamed uniquely
        ↓
(.button becomes .Button_button__a8f3e)
        ↓
A JS mapping object is generated
        ↓
{ button: "Button_button__a8f3e", primary: "Button_primary__c91d2" }
        ↓
That object is what you import as "styles"

Because two different components each get their own unique hash, a .button class in Button.module.css and a completely separate .button class in Card.module.css will never collide, even though you wrote the same class name in both files.

Combining Classes Conditionally

Real components often need more than one class at once — a base style plus a variant, or a base style plus a conditional state like "active" or "disabled." Since styles.button and styles.primary are just plain strings, you can combine them using a template literal or simple string concatenation.

import styles from './Button.module.css';

function Button({ variant = 'primary', children }) {
  const variantClass = variant === 'primary' ? styles.primary : styles.secondary;

  return (
    <button className={`${styles.button} ${variantClass}`}>
      {children}
    </button>
  );
}

export default Button;

For more complex conditional class logic — say, toggling an "active" class based on a boolean prop — many teams use a small utility library like classnames or clsx to keep the logic readable.

import clsx from 'clsx';
import styles from './Button.module.css';

function Button({ isActive, children }) {
  return (
    <button className={clsx(styles.button, { [styles.primary]: isActive })}>
      {children}
    </button>
  );
}

export default Button;

Example: A Styled Alert Component

Here is a small Alert component that uses a base class alongside a conditional variant class, applying everything learned so far.

.alert {
  padding: 12px 16px;
  border-radius: 6px;
  font-size: 0.95rem;
}

.success {
  background-color: #dcfce7;
  color: #166534;
}

.error {
  background-color: #fee2e2;
  color: #991b1b;
}

import styles from './Alert.module.css';

function Alert({ type = 'success', message }) {
  const variantClass = type === 'success' ? styles.success : styles.error;

  return (
    <div className={`${styles.alert} ${variantClass}`}>
      {message}
    </div>
  );
}

export default Alert;

<div class="Alert_alert__f7c21 Alert_error__b02e4">Something went wrong</div>

Common Mistakes

Best Practices

Frequently Asked Questions

Key Takeaways

Summary

CSS Modules give you the best of both worlds: you write completely normal CSS, but every class name is automatically scoped to the component that imports it, removing the risk of accidental global collisions that plain CSS files carry.

Next, you will look at inline styling — passing style objects directly to elements in JSX — and see exactly where it fits compared to the file-based approach you just learned.