How to Use CSS Modules in Next.js ? : A Beginner-Friendly Guide

Styling is a main part of any website. CSS Modules provides a great way to write scoped, maintainable CSS in Next.js. Unlike traditional global CSS, which applies styles to the entire project, CSS Modules allow you to style components individually without worrying about name conflict in the whole project.

In this guide, you are going to learn:

• What CSS Modules are ?
• How to use them in Next.js ?
• How to apply dynamic styles ?
• Best practices and common mistakes.

So, Let’s dive in!

What Are CSS Modules?

CSS Modules locally scope css by automatically creating a unique class name.Now, all class names are accordingly scoped to the specific component they are used in. This thing prevents style conflicts and makes styling more predictable.

• No more class name conflicts!
• Cleaner, component-specific styles
• Works natively with Next.js (no extra setup needed)

Creating a Next.js Project

If you don’t have a Next.js project yet, create one using:

npx create-next-app@latest my-next-app
cd my-next-app

Using CSS Modules in Next.js

By default, Next.js supports CSS Modules right away. You just need to follow the correct file naming convention:

• Create a CSS Module file inside your component’s folder.
• Import the styles in your component.
• Apply styles using className={styles.className}.

For Example, Lets Style a Component with CSS Modules,

# Create a CSS Module file:

Create a new file called Button.module.css inside the styles/ folder (or next to your component).

/* styles/Button.module.css */

.button {
  background-color: #0070f3;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 5px;
  font-size: 16px;
  cursor: pointer;
  transition: background 0.3s;
}

.button:hover {
  background-color: #005bb5;
}

# Import and use it in a component:

// components/Button.js

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

export default function Button() {
  return <button className={styles.button}>Click Me</button>;
}

Now, when you use in your project, it will have its own saperate styles!

Dynamic Styling with CSS Modules

Sometimes, you may need to apply styles dynamically (e.g., based on props or state). You can do this using template literals with classNames.

For Example, Lets add dynamic classes

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

export default function Button({ primary }) {
  return (
    <button className={primary ? styles.primaryButton : styles.secondaryButton}>
      Click Me
    </button>
  );
}

# Update Button.module.css with multiple styles:

.primaryButton {
  background-color: #0070f3;
  color: white;
}

.secondaryButton {
  background-color: grey;
  color: black;
}

Now you can use or to change styles dynamically.

Combining Multiple CSS Module Classes

If you need to apply multiple class names, you can use the classnames package,

npm install classnames

Use it in your component:

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

export default function Button({ primary }) {
  return (
    <button className={cx(styles.button, { [styles.primary]: primary })}>
      Click Me
    </button>
  );
}

This way, styles.button is always applied, and styles.primary is applied only if primary is true.

Using Global CSS Alongside CSS Modules

CSS Modules are scoped by default, but if you need global styles (like for a reset or utility classes), you can use a global CSS file inside the styles/ folder.For Example, Let's add Global CSS,

1. Create a styles/globals.css file:

/* styles/globals.css */
body {
  font-family: Arial, sans-serif;
  margin: 0;
  padding: 0;
  background: #f5f5f5;
}

2. Import it inside _app.js:

// pages/_app.js

import '../styles/globals.css';

export default function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

Now the styles in globals.css apply to the whole application.

Best Practices for Using CSS Modules in Next.js

• Use CSS Modules for component-specific styles please avoid global styles unless necessary.
• Follow naming conventions like ComponentName.module.css to keep files organized and well structured.
• Use meaningful class names just like btn-primary is better than .blue-button right
• Use dynamic class names when and where needed using props, state, or the classnames package
• Keep global styles minimal do reset styles, typography, utility classes when and where necessary.

FAQ

Q. Can I use Tailwind CSS with CSS Modules in Next.js?
A. Yes absolutely, You can combine Tailwind CSS for utility-based styling and CSS Modules for component-specific styles that make a perfect combo.

Q. Do CSS Modules work with TypeScript?
A. Yup, If using TypeScript, create a declaration file (d.ts) for CSS Modules:

// global.d.ts
declare module '*.module.css';
declare module '*.module.scss';

Q. Should I use CSS Modules or Styled Components?
A. Yup, Both are great! Use CSS Modules for scoped, file-based styles. Use Styled Components if you prefer CSS-in-JS with dynamic styling.

Conclusion

CSS Modules in Next.js provide a simple, scalable, and conflict-free way to style your components in next.js. Whether you’re working on a small project or a large-scale application, they help keep your styles modular and maintainable.

So, start using CSS Modules today and keep your styles clean, isolated, and bug-free today!