CSS Modules in React: Scoped Styling Without the Headache

#webdev #react #beginners #frontend

Introduction

In this blog, we’ll discuss what CSS Modules in React are, why we use them, and what problems they solve. We’ll also look at an example to understand the concepts better. CSS Modules provide a modular way of defining CSS styles for a component. Developers can define CSS styles for a component without name clashes. I’ll explain this later in the blog.

What Are CSS Modules?

CSS Modules allow us to define styles for a component. As these are defined for a specific component, it reduces global CSS conflicts. CSS Modules are local styles by default. When classes are defined in CSS Modules, they are transformed into unique identifiers at build time.

What Problems Do CSS Modules Solve?

You have probably faced situations where your desired styles do not work. This issue often arises in projects with multiple developers. For example, you define CSS styles for one component. Another developer defines the same class with different styles. When you use the class in your component, your styles are not working. This is because you both have defined the same class with different styling. That creates unintentional name clashes.

Also, the developers add CSS styles and classes in CSS files. They do not remove the CSS styles/classes from the codebase, thinking that some other component might be using this styling. That results in the CSS file becoming larger over time. CSS Modules solve these issues.

Why Use CSS Modules in React?

Developers use CSS Modules because:

It avoids global CSS conflicts.
It allows component-level styling.
It is easier to maintain.
No headache of creating unique class names.

How CSS Modules Work (Concept)

To work with CSS Modules, you should consider the following points. The CSS filename would be like this Component.module.css. Here Component is the name of your component. (Component.module.css is usually named after the component for clarity, but React does not enforce this strictly.) module.css implies that this is a CSS module. Component.module.css implies that this CSS module contains the styles for Component. For example, if a component is named Item. The CSS module file would be named Item.module.css. React (via the bundler) transforms CSS Module class names into unique identifiers during development and build time. Like .list-item would become ._list-item_zpzj8_1. React converts your CSS classes into an object. You can apply the styles using an import statement in the React component. You can access CSS module classes in a React component using dot-notation or bracket-notation of the object in JS. CSS Modules work out of the box in popular React setups like Create React App, Vite, and Next.js.

Using CSS Modules in a React Project (Example)

This is my component:

function App() {
  return (
    <>
      <h2>Hello World</h2>
      <p>Using CSS Module</p>
    </>
  );
}

I want to change the text color and its background color of both the heading and paragraph. My component name is App. So, I would create App.module.css file for defining styles. In my App.module.css file, I would define my component’s styling as:

.main-heading {
  background-color: aqua;
  color: white;
}
.paragraph {
  background-color: chartreuse;
  color: antiquewhite;
}

Now, import this styling into the App.jsx (App component) by adding this line:

import styles from './App.module.css'

After this, you can apply your defined classes to your component. Use dot-notation or bracket notation to use styles (Because styles/classes are converted into an object). Like:

import styles from "./App.module.css";
function App() {
  return (
    <>
      {/* Using Bracket Notation */}
      <h2 className={styles["main-heading"]}>Hello World</h2>
      {/* Using Dot-Notation*/}
      <p className={styles.paragraph}>Using CSS Module</p>
    </>
  );
}

export default App;

In this way, your styles are applied.

Transformation of class names: In this example, when I inspected the styling of the app in the browser. The .main-heading is transformed into ._main-heading_zpzj8_1 and .paragraph into ._paragraph_zpzj8_9. (In your case, they might be different.) That’s how CSS Modules avoid global CSS conflicts. You can also use global CSS along with CSS module styling as:

import styles from "./App.module.css";
function App() {
  return (
    <>
      {/* Using Bracket Notation */}
      <h2 className={`${styles["main-heading"]} text-center`}>Hello World</h2>
      {/* Using Dot-Notation*/}
      <p className={`${styles.paragraph} text-center`}>Using CSS Module</p>
    </>
  );
}

export default App;

Common Mistakes to Avoid

Using class instead of className

Forgetting module.css

Incorrect import syntax

Trying to use global selectors like body inside CSS Modules

Forgetting to import the CSS module file

When Should You Use CSS Modules?

Small to medium React projects
Component-based UI
Teams where CSS conflicts are common

Conclusion

In this blog, we discussed in detail what CSS Modules are, why and how to use them, and what problems they solve. I explained the concepts in a beginner-friendly way and showed the exact process step-by-step. If you feel it is complicated at first, don’t worry. You will master this by practice. I encourage you to practice following along with the blog to develop a better understanding. Feel free to comment below if you need any help. I’ll be happy to help you.