1 | # React CSS components
|
2 |
|
3 | [![Join the chat at https://gitter.im/andreypopp/react-css-components](https://img.shields.io/badge/gitter-join%20chat-green.svg)](https://gitter.im/andreypopp/react-css-components)
|
4 | [![Travis build status](https://img.shields.io/travis/andreypopp/react-css-components/master.svg)](https://travis-ci.org/andreypopp/react-css-components)
|
5 | [![npm](https://img.shields.io/npm/v/react-css-components.svg)](https://www.npmjs.com/package/react-css-components)
|
6 |
|
7 |
|
8 |
|
9 | **Table of Contents**
|
10 |
|
11 | - [Motivation](#motivation)
|
12 | - [Installation & Usage](#installation-&-usage)
|
13 | - [Base components](#base-components)
|
14 | - [DOM components](#dom-components)
|
15 | - [Composite components](#composite-components)
|
16 | - [Variants](#variants)
|
17 | - [Named variants](#named-variants)
|
18 | - [JavaScript expressions](#javascript-expressions)
|
19 | - [Customizing CSS loading](#customizing-css-loading)
|
20 | - [CSS extraction](#css-extraction)
|
21 | - [Using with SASS/SCSS/LESS/Stylus/...](#using-with-sassscsslessstylus)
|
22 | - [Using with PostCSS (including autoprefixer)](#using-with-postcss-including-autoprefixer)
|
23 |
|
24 |
|
25 |
|
26 | ## Motivation
|
27 |
|
28 | Define React presentational components with CSS (or even SASS or Less if you
|
29 | like).
|
30 |
|
31 | The implementation is based on [CSS modules][]. In fact React CSS Components is
|
32 | just a thin API on top of CSS modules.
|
33 |
|
34 | **NOTE:** The current implementation is based on Webpack but everything is ready
|
35 | to be ported onto other build systems (generic API is here just not yet
|
36 | documented). Raise an issue or better submit a PR if you have some ideas.
|
37 |
|
38 | ## Installation & Usage
|
39 |
|
40 | Install from npm:
|
41 |
|
42 | % npm install react-css-components style-loader css-loader
|
43 |
|
44 | Configure in `webpack.config.js`:
|
45 |
|
46 | ```js
|
47 | module.exports = {
|
48 | ...
|
49 | module: {
|
50 | loaders: [
|
51 | {
|
52 | test: /\.react.css$/,
|
53 | loader: 'react-css-components',
|
54 | }
|
55 | ]
|
56 | }
|
57 | ...
|
58 | }
|
59 | ```
|
60 | Now you can author React components in `Styles.react.css`:
|
61 | ```css
|
62 | Label {
|
63 | color: red;
|
64 | }
|
65 |
|
66 | Label:hover {
|
67 | color: white;
|
68 | }
|
69 | ```
|
70 |
|
71 | And consume them like regular React components:
|
72 | ```js
|
73 | import {Label} from './styles.react.css'
|
74 |
|
75 | <Label /> // => <div class="<autogenerated classname>">...</div>
|
76 | ```
|
77 |
|
78 | ## Base components
|
79 |
|
80 | ### DOM components
|
81 |
|
82 | By default React CSS Components produces styled `<div />` components. You can
|
83 | change that by defining `base:` property:
|
84 |
|
85 | ```css
|
86 | FancyButton {
|
87 | base: button;
|
88 | color: red;
|
89 | }
|
90 | ```
|
91 |
|
92 | Now `<FancyButton />` renders into `<button />`:
|
93 |
|
94 | ```js
|
95 | import {FancyButton} from './styles.react.css'
|
96 |
|
97 | <FancyButton /> // => <button class="<autogenerated classname>">...</button>
|
98 | ```
|
99 |
|
100 | ### Composite components
|
101 |
|
102 | In fact any React components which accepts `className` props can be used as a
|
103 | base. That's means that React CSS Components can be used as theming tool for any
|
104 | UI library.
|
105 |
|
106 | Example:
|
107 |
|
108 | ```css
|
109 | DangerButton {
|
110 | base: react-ui-library/components/Button;
|
111 | color: red;
|
112 | }
|
113 | ```
|
114 |
|
115 | ## Variants
|
116 |
|
117 | Variants is a mechanism which allows to define styling variants for a component.
|
118 |
|
119 | ### Named variants
|
120 |
|
121 | You can define additional styling variants for your components:
|
122 |
|
123 | ```css
|
124 | Label {
|
125 | color: red;
|
126 | }
|
127 |
|
128 | Label:emphasis {
|
129 | font-weight: bold;
|
130 | }
|
131 | ```
|
132 |
|
133 | They are compiled as CSS classes which then can be controlled from JS via
|
134 | `variant` prop:
|
135 |
|
136 | ```js
|
137 | <Label variant={{emphasis: true}} /> // sets both classes with `color` and `font-weight`
|
138 | ```
|
139 | ### JavaScript expressions
|
140 |
|
141 | You can define variants which are conditionally applied if JS expression against
|
142 | props evaluates to a truthy value.
|
143 |
|
144 | Example:
|
145 |
|
146 | ```css
|
147 | Label {
|
148 | color: red;
|
149 | }
|
150 |
|
151 | Label:prop(mode == "emphasis") {
|
152 | font-weight: bold;
|
153 | }
|
154 | ```
|
155 |
|
156 | Note that any free variable reference a member of `props`, thus in JS `mode`
|
157 | becomes `props.mode` in the example above.
|
158 |
|
159 | They are compiled as CSS classes as well. JS expressions within `prop(..)` are
|
160 | used to determine if corresponding CSS classes should be applied to DOM:
|
161 |
|
162 | ```js
|
163 | <Label mode="emphasis" /> // sets both classes with `color` and `font-weight`
|
164 | ```
|
165 |
|
166 | ## Customizing CSS loading
|
167 |
|
168 | By default React CSS components loads CSS using `style-loader!css-loader` loader
|
169 | chain. That could be configured differently using `loadCSS` loader parameter.
|
170 |
|
171 | This could be used to enable features such as *CSS extraction*, processing
|
172 | stylesheets with *PostCSS/Autoprefixer* or even authoring stylesheets with
|
173 | *SASS* or *LESS*.
|
174 |
|
175 | ### CSS extraction
|
176 |
|
177 | See the [complete example](./examples/css-extraction/webpack.config.js) which
|
178 | configures
|
179 | [`extract-text-webpack-plugin`](https://github.com/webpack/extract-text-webpack-plugin)
|
180 | to extract stylesheets to a separate chunk.
|
181 |
|
182 | ### Using with SASS/SCSS/LESS/Stylus/...
|
183 |
|
184 | See the [complete example](./examples/sass/webpack.config.js) which
|
185 | uses SASS/SCSS to create React components.
|
186 |
|
187 | ### Using with PostCSS (including autoprefixer)
|
188 |
|
189 | See the [complete example](./examples/postcss//webpack.config.js) which
|
190 | configures PostCSS with Autoprefixer to automatically add vendor prefixes to
|
191 | stylesheets.
|
192 |
|
193 | [CSS modules]: https://github.com/css-modules/css-modules
|