This repo is a collection of simple demos of CSS Modules.

If you don't know, CSS Modules is a method to add local scope and module dependencies into CSS.

First, clone the repo.

$ git clone https://github.com/ruanyf/css-modules-demos.git

Install the dependencies.

$ cd css-modules-demos
$ npm install

Run the first demo.

$ npm run demo01

Open http://localhost:8080 , see the result.

Then run demo02, demo03...

1. Local Scope
2. Global Scope
3. Customized Hash Class Name
4. Composing CSS Classes
5. Import Other Modules
6. Exporting Values Variables

demo / sources

CSS rules are global. The only way of making a local-scoped rule is to generate a unique class name, so no other selectors will have collisions with it. That is exactly what CSS Modules do.

The following is a React component App.js.

import React from 'react';
import style from './App.css';

export default () => {
  return (
    <h1 className={style.title}>
      Hello World
    </h1>
  );
};

In above codes, we import a CSS module from App.css into a style object, and use style.title to represent a class name.

.title {
  color: red;
}

The build runner will compile the class name style.title into a hash string.

<h1 class="_3zyde4l1yATCOkgn-DBWEL">
  Hello World
</h1>

And App.css is also compiled.

._3zyde4l1yATCOkgn-DBWEL {
  color: red;
}

Now this class name becomes unique and only effective to the App component.

CSS Modules provides plugins for different build runners. This repo uses css-loader for Webpack, since it support CSS Modules best and is easy to use. By the way, if you don't know Webpack, please read my tutorial Webpack-Demos.

The following is our webpack.config.js.

module.exports = {
  entry: __dirname + '/index.js',
  output: {
    publicPath: '/',
    filename: './bundle.js'
  },
  module: {
    loaders: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        loader: 'babel',
        query: {
          presets: ['es2015', 'stage-0', 'react']
        }
      },
      {
        test: /\.css$/,
        loader: "style-loader!css-loader?modules"
      },
    ]
  }
};

The magic line is loader: "style-loader!css-loader?modules", which appends the query parameter modules after css-loader enabling the CSS Modules feature.

Now run the demo.

$ npm run demo01

Open http://localhost:8080, you should see the h1 in red.

demo / sources

The syntax :global(.className) could be used to declare a global selector explicitly. CSS Modules will not compile this class name into hash string.

First, add a global class into App.css.

.title {
  color: red;
}

:global(.title) {
  color: green;
}

Then use the global CSS class in App.js.

import React from 'react';
import styles from './App.css';

export default () => {
  return (
    <h1 className="title">
      Hello World
    </h1>
  );
};

Run the demo.

$ npm run demo02

Open http://localhost:8080, you should see the h1 title in green.

CSS Modules also has a explicit local scope syntax :local(.className) which is equivalent to .className. So the above App.css could be written in another form.

:local(.title) {
  color: red;
}

:global(.title) {
  color: green;
}

demo / sources

CSS-loader's default hash algorithm is [hash:base64], which compiles.title into something like ._3zyde4l1yATCOkgn-DBWEL.

You could customize it in webpack.config.js.

module: {
  loaders: [
    // ...
    {
      test: /\.css$/,
      loader: "style-loader!css-loader?modules&localIdentName=[path][name]---[local]---[hash:base64:5]"
    },
  ]
}

Run the demo.

$ npm run demo03

You will find .title hashed into demo03-components-App---title---GpMto.

demo / sources

In CSS Modules, a selector could inherit another selector's rules, which is called "composition".

We let .title inherit .className in App.css.

.className {
  background-color: blue;
}

.title {
  composes: className;
  color: red;
}

App.js is the same.

import React from 'react';
import style from './App.css';

export default () => {
  return (
    <h1 className={style.title}>
      Hello World
    </h1>
  );
};

Run the demo.

$ npm run demo04

You should see a red h1 title in a blue background.

After the building process, App.css is converted into the following codes.

._2DHwuiHWMnKTOYG45T0x34 {
  color: red;
}

._10B-buq6_BEOTOl9urIjf8 {
  background-color: blue;
}

And the HTML element h1's class names should look like <h1 class="_2DHwuiHWMnKTOYG45T0x34 _10B-buq6_BEOTOl9urIjf8">,

demo / sources

You also could inherit rules from another CSS file.

another.css

.className {
  background-color: blue;
}

App.css

.title {
  composes: className from './another.css';
  color: red;
}

Run the demo.

$ npm run demo05

You should see a red h1 title in a blue background.

demo / sources

You could use variables in CSS Modules. This feature is provided by PostCSS and the postcss-modules-values plugin.

$ npm install --save postcss-loader postcss-modules-values

Add postcss-loader into webpack.config.js.

var values = require('postcss-modules-values');

module.exports = {
  entry: __dirname + '/index.js',
  output: {
    publicPath: '/',
    filename: './bundle.js'
  },
  module: {
    loaders: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        loader: 'babel',
        query: {
          presets: ['es2015', 'stage-0', 'react']
        }
      },
      {
        test: /\.css$/,
        loader: "style-loader!css-loader?modules!postcss-loader"
      },
    ]
  },
  postcss: [
    values
  ]
};

Next, set up your values/variables in colors.css.

@value blue: #0c77f8;
@value red: #ff0000;
@value green: #aaf200;

Then import them into App.css.

@value colors: "./colors.css";
@value blue, red, green from colors;

.title {
  color: red;
  background-color: blue;
}

Run the demo.

$ npm run demo06

MIT