You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
React CSS Modules implement automatic mapping of class names to CSS modules. Every CSS class is assigned a local-scoped identifier with a global unique name. CSS Modules enable a modular and reusable CSS!
6
+
React CSS Modules implement automatic mapping of CSS modules. Every CSS class is assigned a local-scoped identifier with a global unique name. CSS Modules enable a modular and reusable CSS!
7
7
8
8
-[What's the Problem?](#whats-the-problem)
9
+
-[The Implementation](#theimplementation)
9
10
-[Usage](#usage)
10
11
-[Module Bundler](#module-bundler)
11
12
- [webpack](#webpack)
12
13
- [Browserify](#browserify)
13
14
-[Decorator](#decorator)
14
15
-[Options](#options)
15
-
-[`useModuleName`](#usemodulename)
16
16
-[`allowMultiple`](#allowmultiple)
17
-
-[`keepOriginal`](#keeporiginal)
18
-
-[`errorNotFound`](#errornotfound)
17
+
-[`errorWhenNotFound`](#errorwhennotfound)
19
18
-[SASS, SCSS, LESS and other CSS Preprocessors](#sass-scss-less-and-other-css-preprocessors)
20
19
-[Global CSS](#global-css)
21
20
-[Multiple CSS Classes](#multiple-css-classes)
22
21
23
22
## What's the Problem?
24
23
25
-
[CSS modules](https://github.com/css-modules/css-modules) are awesome. If you are not familiar with CSS modules, it is a concept of using a module bundler such as [webpack](http://webpack.github.io/docs/) to load CSS scoped to a particular document. CSS modules loader will generate a unique name for a each CSS class at the time of loading the CSS. Refer to [webpack-demo](https://css-modules.github.io/webpack-demo/) for a full example.
24
+
[CSS Modules](https://github.com/css-modules/css-modules) are awesome. If you are not familiar with CSS Modules, it is a concept of using a module bundler such as [webpack](http://webpack.github.io/docs/) to load CSS scoped to a particular document. CSS module loader will generate a unique name for a each CSS class at the time of loading the CSS document ([Interoperable CSS](https://github.com/css-modules/icss)to be precise). To see CSS Modules in practice, [webpack-demo](https://css-modules.github.io/webpack-demo/).
26
25
27
-
In the context of React, this looks like this:
26
+
In the context of React, CSS Modules look like this:
28
27
29
28
```js
30
29
importReactfrom'react';
@@ -43,9 +42,9 @@ export default class Car extends React.Component {
43
42
Rendering the component will produce a markup similar to:
@@ -57,8 +56,10 @@ However, this approach has several disadvantages:
57
56
58
57
* You have to use `camelCase` CSS class names.
59
58
* You have to use `styles` object whenever constructing a `className`.
59
+
* Mixing CSS Modules and global CSS classes is cumbersome.
60
+
* Reference to an undefined CSS Module resolves to `undefined` without a warning.
60
61
61
-
React CSS Modules enables seamless CSS modules for React, e.g.
62
+
React CSS Modules component automates loading of CSS Modules using `moduleName` property, e.g.
62
63
63
64
```js
64
65
importReactfrom'react';
@@ -67,36 +68,49 @@ import CSSModules from 'react-css-modules';
67
68
68
69
classCarextendsReact.Component {
69
70
render () {
70
-
return<div className='car'>
71
-
<div className='front-door'></div>
72
-
<div className='back-door'></div>
71
+
return<div moduleName='car'>
72
+
<div moduleName='front-door'></div>
73
+
<div moduleName='back-door'></div>
73
74
</div>;
74
75
}
75
76
}
76
77
77
78
exportdefaultCSSModules(Car, styles);
78
79
```
79
80
80
-
`CSSModules` extends `Car``render` method. It will look for CSS classes in `./car.css` that match CSS class names in `ReactElement``className` and will replace/append the matching unique class names to `className` declaration.
81
+
Using `react-css-modules`:
82
+
83
+
* You are not forced to use the `camelCase` naming convention.
84
+
* You do not need to refer to the `styles` object every time you use a CSS Module.
85
+
* There is clear distinction between global CSS and CSS Modules, e.g.
* You are warned when `moduleName` refers to an undefined CSS Module ([`errorWhenNotFound`](#errorwhennotfound) option).
92
+
* You can enforce use of a single CSS module per `ReactElement` ([`allowMultiple`](#allowmultiple) option).
81
93
82
-
Refer to the [react-css-modules-examples](https://github.com/gajus/react-css-modules-examples) repository for a complete usage example.
94
+
## The Implementation
95
+
96
+
`react-css-modules` extends `render` method of the target component. It will use the value of `moduleName` to look for CSS Modules in the associated styles object and will append the matching unique CSS class names to the `ReactElement``className` property value.
* Setting up a module bundler to load your [ICSS](https://github.com/css-modules/icss).
104
+
* Setting up a [module bundler](#modulebundler) to load the [Interoperable CSS](https://github.com/css-modules/icss).
91
105
*[Decorating](#decorator) your component using `react-css-modules`.
92
106
93
107
### Module Bundler
94
108
95
109
#### webpack
96
110
97
111
* Install [`style-loader`](https://www.npmjs.com/package/style-loader) and [`css-loader`](https://www.npmjs.com/package/css-loader).
98
-
* You will also need to use [`extract-text-webpack-plugin`](https://www.npmjs.com/package/extract-text-webpack-plugin) to aggregate the CSS into a single file.
99
-
* Setup a `/\.css$/` loader:
112
+
* You need to use [`extract-text-webpack-plugin`](https://www.npmjs.com/package/extract-text-webpack-plugin) to aggregate the CSS into a single file.
113
+
* Setup `/\.css$/` loader:
100
114
101
115
```js
102
116
{
@@ -113,7 +127,7 @@ new ExtractTextPlugin('app.css', {
113
127
})
114
128
```
115
129
116
-
Refer to [webpack-demo](https://github.com/css-modules/webpack-demo) or [react-css-modules-examples](https://github.com/gajus/react-css-modules-examples) for a complete setup.
130
+
Refer to [webpack-demo](https://github.com/css-modules/webpack-demo) or [react-css-modules-examples](https://github.com/gajus/react-css-modules-examples) for an example of a complete setup.
117
131
118
132
#### Browserify
119
133
@@ -124,16 +138,16 @@ Refer to [`css-modulesify`](https://github.com/css-modules/css-modulesify).
124
138
```js
125
139
/**
126
140
* @typedefCSSModules~Options
127
-
* @property{Boolean}allowMultiple Determines whether `className` can have multiple class names. Throws an error when the constrained is not met. Default: true.
128
-
* @property{Boolean}keepOriginal Determines whether the original `className` value is kept in addition to the appended CSS modules styles CSS class name. Default: true.
129
-
* @property{Boolean}errorNotFound Determines whether an error is raised if `className` defines a CSS class(es) that is not present in the CSS modules styles. Default: false.
Keeps original CSS class name in addition to the names of the CSS Modules.
222
-
223
-
When `true`, the following `ReactElement`:
224
-
225
-
```js
226
-
<div className='foo bar'/>
227
-
```
228
-
229
-
will be rendered with a `className` property `foo component__foo___2w27N bar component__bar__1oVw5`.
230
-
231
-
#### `errorNotFound`
232
-
233
-
Default: `false`.
234
-
235
-
Throws an error when class name cannot be mapped to a CSS Module.
227
+
Throws an error when `moduleName` cannot be mapped to an existing CSS Module.
236
228
237
229
## SASS, SCSS, LESS and other CSS Preprocessors
238
230
239
-
[ICSS](https://github.com/css-modules/icss) is compatible with the CSS Preprocessors. All you need is to add the preprocessor to the chain of loaders, e.g. in the case of webpack it is as simple as installing `sass-loader` and adding `!sass` to the end of the `style-loader` loader chain declaration (loaders are processed from right to left):
231
+
[Interoperable CSS](https://github.com/css-modules/icss) is compatible with the CSS Preprocessors. To use a preprocessor, all you need to do is add the preprocessor to the chain of loaders, e.g. in the case of webpack it is as simple as installing `sass-loader` and adding `!sass` to the end of the `style-loader` loader query (loaders are processed from right to left):
240
232
241
233
```js
242
234
{
@@ -255,13 +247,11 @@ CSS Modules does not restrict you from using global CSS.
255
247
}
256
248
```
257
249
258
-
When using global CSS, you need to enable [`keepOriginal`](#keeporiginal) option.
250
+
However, use global CSS with caution. With CSS Modules, there are only a handful of valid use cases for global CSS (e.g. [normalization](https://github.com/necolas/normalize.css/)).
259
251
260
-
Use global CSS with caution. With CSS Modules, there are only a handful of valid use cases for global CSS (e.g. [normalization](https://github.com/necolas/normalize.css/)).
252
+
## Multiple CSS Modules
261
253
262
-
## Multiple CSS Classes
263
-
264
-
CSS modules promote composition pattern, i.e. every CSS class that is used in a component should define all properties required to describe the element, e.g.
254
+
CSS Modules promote composition pattern, i.e. every CSS Module that is used in a component should define all properties required to describe an element, e.g.
265
255
266
256
```css
267
257
.button {
@@ -281,9 +271,11 @@ CSS modules promote composition pattern, i.e. every CSS class that is used in a
281
271
}
282
272
```
283
273
284
-
To learn more about composing CSS rules, I suggest reading Glen Maddern article about [CSS Modules](http://glenmaddern.com/articles/css-modules) and the official [CSS modules spec](https://github.com/css-modules/css-modules).
274
+
Composition promotes better separation of markup and style using semantics that would be hard to achieve without CSS Modules.
275
+
276
+
To learn more about composing CSS rules, I suggest reading Glen Maddern article about [CSS Modules](http://glenmaddern.com/articles/css-modules) and the official [spec of the CSS Modules](https://github.com/css-modules/css-modules).
285
277
286
-
Using React CSS Modules, you can map as many CSS classes to the element as you want. `CSSModules` will append a unique class name for every class name it matches in the `className` declaration, e.g.
278
+
That said, if you enable [`allowMultiple`](#allowmultiple) option, you can map multiple CSS Modules to a single `ReactElement`. `react-css-modules` will append a unique class name for every CSS Module it matches in the `moduleName` declaration, e.g.
287
279
288
280
```css
289
281
.button {
@@ -296,9 +288,7 @@ Using React CSS Modules, you can map as many CSS classes to the element as you w
296
288
```
297
289
298
290
```js
299
-
<div className='button active'></div>
291
+
<div moduleName='button active'></div>
300
292
```
301
293
302
-
This will map both [ICSS](https://github.com/css-modules/icss) CSS classes to the target element.
303
-
304
-
However, I encourage you to use composition whenever possible. Composition promotes better separation of markup from style sheets using semantics that would be hard to achieve without CSS modules. You can enforce one CSS class name per `className` using [`allowMultiple` option](#usage).
294
+
This will map both [Interoperable CSS](https://github.com/css-modules/icss) CSS classes to the target element.
0 commit comments