CSS Modules Demos

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.

Usage

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...

Demo01: Local Scope

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.

Demo02: Global Scope

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;
}

Demo03: Customized Hash Class Name

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.

Demo04: Composing CSS Classes

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">,

Demo05: Import Other Modules

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.

Demo06: Exporting Values Variables

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

License

MIT