Need help with css-modules?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

15.5K Stars 525 Forks 69 Commits 112 Opened issues


Documentation about css-modules

Services available


Need anything else?

Contributors list

CSS Modules

A CSS Module is a CSS file in which all class names and animation names are scoped locally by default. All URLs (

) and
are in module request format (
means relative,
means in modules folder, i. e. in

CSS Modules compile to a low-level interchange format called ICSS or Interoperable CSS, but are written like normal CSS files:

/* style.css */
.className {
  color: green;

When importing the CSS Module from a JS Module, it exports an object with all mappings from local names to global names.

import styles from "./style.css";
// import { className } from "./style.css";

element.innerHTML = '



For local class names camelCase naming is recommended, but not enforced.

This is recommended because the common alternative, kebab-casing may cause unexpected behavior when trying to access style.class-name as a dot notation. You can still work around kebab-case with bracket notation (eg.

) but
is cleaner.


switches to global scope for the current selector respective identifier.
@keyframes :global(xxx)
declares the stuff in parenthesis in the global scope.


for local scope.

If the selector is switched into global mode, global mode is also activated for the rules. (This allows us to make

animation: abc;


.localA :global .global-b .global-c :local(.localD.localE) .global-d


It's possible to compose selectors.

.className {
  color: green;
  background: red;

.otherClassName { composes: className; color: yellow; }

There can be multiple

rules, but
rules must be before other rules. Extending works only for local-scoped selectors and only if the selector is a single class name. When a class name composes another class name, the CSS Module exports both class names for the local class. This can add up to multiple class names.

It's possible to compose multiple classes with

composes: classNameA classNameB;


Composing from other files

It's possible to compose class names from other CSS Modules.

.otherClassName {
  composes: className from "./style.css";

Note that when composing multiple classes from different files the order of appliance is undefined. Make sure to not define different values for the same property in multiple class names from different files when they are composed in a single class.

Note that composing should not form a circular dependency. Elsewise it's undefined whether properties of a rule override properties of a composed rule. The module system may emit an error.

Best if classes do a single thing and dependencies are hierarchic.

Composing from global class names

It's possible to compose from global class names.

.otherClassName {
  composes: globalClassName from global;

Usage with preprocessors

Preprocessors can make it easy to define a block global or local.

i. e. with less.js

:global {
  .global-class-name {
    color: green;


modular and reusable CSS!

  • No more conflicts.
  • Explicit dependencies.
  • No global scope.



  • 04/2015:
    feature in css-loader (webpack) allows local scoped selectors (later renamed to
    local scope
    ) by @sokra
  • 05/2015:
    local scope
    by default (see blog post) by @markdalgleish
  • 05/2015:
    feature in css-loader allow to compose local or imported class names by @sokra
  • 05/2015: First CSS Modules spec document and github organization with @sokra, @markdalgleish and @geelen
  • 06/2015:
    renamed to
  • 06/2015: PostCSS transformations to transform CSS Modules into an intermediate format (ICSS)
  • 06/2015: Spec for ICSS as common implementation format for multiple module systems by @geelen
  • 06/2015: Implementation for jspm by @geelen and @guybedford
  • 06/2015: Implementation for browserify by @joshwnj, @joshgillies and @markdalgleish
  • 06/2015: webpack's css-loader implementation updated to latest spec by @sokra



Webpack's css-loader in module mode replaces every local-scoped identifier with a global unique name (hashed from module name and local identifier by default) and exports the used identifier.

Extending adds the source class name(s) to the exports.

Extending from other modules first imports the other module and then adds the class name(s) to the exports.

Server-side and static websites

PostCSS-Modules allows to use CSS Modules for static builds and the server side with Ruby, PHP or any other language or framework.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.