An easy, consistent way to override CSS modules in React components.



## CSS Modules 

[CSS modules](https://github.com/css-modules/css-modules) are fantastic because they scope your CSS.  No longer does everything have to live in the global namespace.

A natural boundary to scope CSS to is within a web component.  A React component can have a corresponding `*.css` file to accompany it with all the related styles, and it feels very natural.

## Overriding Styles

Of course, as soon as you have boxed-up some functionality -- in this case some markup and styles inside a component with accompanying css -- you're going to have occasion to open the box and customize it.

Because the scoping of CSS module selectors happens by hashing them at build time, this can be challenging to predictably override.

If you use your CSS module like this in this theoretical `List` component:

```js
import css from './list.css'

export default props => 
  <ul className={css.list}>
    <li className={css.listItem}>item!</li>
  </ul>
```

You're going to be hard-pressed to override this from the outside, or client side, of this module.  This is because you've coupled your component directly to this `css` module-scoped variable without any way to override it from the outside.

## React-Styleable

[react-styleable](https://www.npmjs.com/package/react-styleable) aims to improve this by providing an easy, consistent way to override CSS modules.

Instead of using the `css` variable directly, you would pass it to the higher-order component provided by `react-styleable` and then access the css selectors via `props.css`:

```js
import styleable from 'react-styleable'

import css from './list.css'

export default styleable(css)(props => 
  <ul className={props.css.list}>
    <li className={props.css.listItem}>item!</li>
  </ul>
)
```

## Overriding Styles

Because you are now accessing the CSS via the props (`props.css`), you have an opportunity to change the CSS via props.  Props, after all, are React's way of passing parameters into your component.

The `styleable` higher-order component will merge the `props.css` object with overriding styles as needed.

Let's say that you created a custom stylesheet, where the list was originally white now should be a darker color.

The original stylesheet snippet (`list.css`) looks like:

```css
.list {
  background: #fff;
}
```

And the overriding stylesheet snippet (`list-dark.css`) looks like:

```css
.list {
  background: #555555;
}
```

![overriding list style](https://i.imgur.com/w0exenI.jpg)

When you want to use the `List` component but override the styles, you could pass your new stylesheet:

```js
import css from './list-dark.css'
import List from './list'

<List css={css} />
```

In this usage of `List`, this `.list` selector would get the dark background.  

Note that if there were other selectors in the overriding css file that they too would be overridden since this is a _full_ override of the stylesheet.  

For a partial override, we could be more precise, only overriding the `.list` selector specifically:

```js
import css from './list-dark.css'
import List from './list'

<List css={{ list: css.list }} />
```

Imagine if we had an app or a component ecosystem where all components were consistent in their usage of such a mechanism.  It'd be easier to override styles -- we'd have a set of more flexible components that could handle the custom styling scenarios that we always seem to run into. 

There are also other methods for overriding CSS modules or component styles.  What are some of the ways that have worked best for you?

An easy, consistent way to override CSS modules in React components.

Override CSS Modules with react-styleable

[CSS Modules](https://github.com/css-modules/css-modules) are das bombe, but you're still stuck in a land where the traditional CSS stylesheet exists, you may have to load both.  Here's a pattern that could potentially work for you.



## Importing CSS

[Webpack](https://webpack.js.org/) is a tool for loading many different kinds of assets as modules into JavaScript.  This means, for instance, that you can import CSS into your JavaScript.  If you import a CSS module in this way, it'll allow you to use that module on a UI component that is built using JavaScript (eg, React):

```js
import css from './my-component.css'
import React from 'react'

const MyComponent = _ => <div className={css.someSelector}></div>
```

We can reference the `css.someSelector` from the `css` variable because it's a CSS module. 

Using Webpack, you can import a traditional CSS stylesheet in the same way:

```js
import './my-component.css'
import React from 'react'

const MyComponent = _ => <div className="someSelector"></div>
```

But the CSS is merely imported but not saved to a variable reference.  There's no need.  The CSS will be made available, usually via something like [`style-loader`](https://github.com/webpack-contrib/style-loader) in a stylesheet on the page.  Thus a simple `className="someSelector"` reference will be enough.

Those are the two worlds that we want to support.  These two methods are so different that they need to be loaded differently.

## Webpack Config

Webpack has a list of loader rules to determine how files get loaded as modules into your code.  Each rule is usually matched by file extension.  That is, the `*.css` files get loaded like stylesheets, and the `*.js` files get loaded like JavaScript code.  

Here we will only explore how to load CSS, but we have two totally different constructs for how our styles will be used: traditional stylesheet and CSS module.  We need to make another distinction to be able to load them differently.  We'll do something akin to making a new file extension by adding a file name suffix to the end of one of these types of files.  We'll choose the CSS module file names because CSS modules are the newcomer tech and a bit more specialized in their usage.  Here's the `webpack.config.js` snippet:

```js
{
  module: {
    rules: [
      {
        test: /^(?!.*?\.module).*\.css$/,
        use: ['style-loader', 'css-loader']
      },
      {
        test: /\.module\.css$/,
        use: ['style-loader', {
          loader: 'css-loader',
          options: {
            modules: true
          }
        }]
      }
    ]
  }
}
```

Both `*.css` and `*.module.css` files are loaded using the [`css-loader`](https://github.com/webpack-contrib/css-loader), but the CSS modules are being loaded with a key extra option enabled: `modules: true`.

That first entry with the [gnarly regex](https://regex101.com/r/rS5uZp/1) is a "negative lookahead" that matches "`*.css` files that don't include a `.module` substring" file names.  If you don't include this negation of `*.module.css` files, your `*.module.css` files will go through both loader rules, causing an error.  Depending on your setup, another option might be to use the [`excludes`](https://webpack.js.org/configuration/module/#rule-exclude) option from Webpack.

Now both are loadable using the same tool in the same config.  All we need to do now is stay consistent in our file naming.

Are there other strategies you've taken to get the same support?

With a little webpack config, you can load both CSS stylesheets and CSS modules, no sweat.

Load Both CSS and CSS Modules With Webpack

Use of postcss-import in your CSS module processing can lead to more selectors than you realized.  Here are some ways to deal with it.



[postcss-import](https://github.com/postcss/postcss-import) is a useful [postcss](http://postcss.org/) plugin.  It allows loading CSS from npm modules by looking up module entry [via `package.json`'s `"style"` attribute](https://github.com/postcss/postcss-import/blob/ac9903b658b1d447f62b9021081051e8b8d42538/lib/resolve-id.js#L22). But if you don't realize that one of its main features is inlining what you `@import`, the consequences can be unexpected.  So what can you do?

## If You Don't Use postcss-import

It's one option to just not use it.  But the plugin does seem to smooth out importing.  You're able to import from `node_modules`, `web_modules`, and utilize that `package.json` `"style"` attribute.  So, I'm keeping it.  Ok, where from here?

## Scenario

Let's say that I have a source CSS file that I'm building into a module with [`css-loader`](https://github.com/webpack-contrib/css-loader), called `source.css`:

```css
.mySelector {
  color: red;
}
```

And something that wants to be imported, `dependency.css`:

```css
.dependencySelector {
  outline: 1px solid blue;
}
```

## No @imports Yet

If I don't import my dependency, then the export object for the `source.css` CSS module will look like:

```
{
  mySelector: "mySelector___oHNuy"
}
```

This is as expected.  No surprises.

## Top-level @import

If we make sure our [`postcss.config.js`](https://github.com/postcss/postcss-loader#config) is running with `postcss-import`:

```js
module.exports = {
  plugins: {
    'postcss-import': {}
  }
}
```

And then add an `@import` of the dependency to our `source.css`:

```css
@import "./dependency.css";
.mySelector {
  color: red;
}
```

We've done nothing to use the dependency or compose with it, but our module export object still changes to:

```js
{
  dependencySelector: "dependencySelector___2HjUz"
  mySelector: "mySelector___oHNuy"
}
```

This is because `postcss-import` is *inlining* everything we `@import`.

## Composes with Top-level Import

Once we use the imported dependency in a `composes` attribute:

```css
@import "./dependency.css";
.mySelector {
  composes: dependencySelector;
  color: red;
}
```

We change the output of the `mySelector` value, where both selector values now are composed:

```js
{
  dependencySelector: "dependencySelector___2HjUz"
  mySelector: "mySelector___oHNuy dependencySelector___2HjUz"
}
```

## Composes From

But let's say that we want to avoid having `dependencySelector` appear in our CSS modules export object.  We can use the `composes: <selector> from <import-path>` syntax:

```css
.mySelector {
  composes: dependencySelector from "./dependency.css";
  color: red;
}
```

This will yield the following CSS module export object:

```js
{
  mySelector: "mySelector___oHNuy dependencySelector___2BS8K"
}
```

This is because the `@import` of the dependency is done within the scope of the `.mySelector` selector, not the entire module.

## Import Variables

There's another way I've gotten around this issue.  That is to `@import` only variables.  If it is only variable values that you need, you can separate them into another file and import them without worrying about cluttering your CSS module export object.  Since this is one of the style elements that we share most often, it works pretty well.

Let's make a new file, `dependency-vars.css`:

```css
:root {
  --aDependencyVar: orange;
}
```

Then if I use it, even if imported at the top-level:

```css
@import "./dependency-vars.css";
.mySelector {
  color: red;
  border: 1px solid var(--aDependencyVar);
}
```

It still yields an uncluttered CSS module export object:

```js
{
  mySelector: "mySelector___oHNuy"
}
```

Have you run into this issue?  Or is it a non-issue for you?  What are some other ways that you've addressed it and kept your CSS modules uncluttered?

Use of postcss-import in your CSS module processing can lead to more selectors than you realized.