1 | [![Travis Status][trav_img]][trav_site]
|
2 | [![AppVeyor Status][appveyor_img]][appveyor_site]
|
3 | [![Coverage Status][cov_img]][cov_site]
|
4 | [![NPM Package][npm_img]][npm_site]
|
5 | [![Dependency Status][david_img]][david_site]
|
6 | ![gzipped size][size_img]
|
7 |
|
8 | # Radium
|
9 |
|
10 | ```
|
11 | npm install radium
|
12 | ```
|
13 |
|
14 | Radium is a set of tools to manage inline styles on React elements. It gives you powerful styling capabilities without CSS.
|
15 |
|
16 | _Inspired by_ <a href="https://speakerdeck.com/vjeux/react-css-in-js">React: CSS in JS</a>
|
17 | by <a href="https://twitter.com/Vjeux">vjeux</a>.
|
18 |
|
19 | ## Overview
|
20 |
|
21 | Eliminating CSS in favor of inline styles that are computed on the fly is a powerful approach, providing a number of benefits over traditional CSS:
|
22 |
|
23 | - Scoped styles without selectors
|
24 | - Avoids specificity conflicts
|
25 | - Source order independence
|
26 | - Dead code elimination
|
27 | - Highly expressive
|
28 |
|
29 | Despite that, there are some common CSS features and techniques that inline styles don't easily accommodate: media queries, browser states (:hover, :focus, :active) and modifiers (no more .btn-primary!). Radium offers a standard interface and abstractions for dealing with these problems.
|
30 |
|
31 | When we say expressive, we mean it: math, concatenation, regex, conditionals, functions–JavaScript is at your disposal. Modern web applications demand that the display changes when data changes, and Radium is here to help.
|
32 |
|
33 | For a short technical explanation, see [How does Radium work?](#how-does-radium-work).
|
34 |
|
35 | ## Features
|
36 |
|
37 | * Conceptually simple extension of normal inline styles
|
38 | * Browser state styles to support `:hover`, `:focus`, and `:active`
|
39 | * Media queries
|
40 | * Automatic vendor prefixing
|
41 | * Keyframes animation helper
|
42 | * ES6 class and `createClass` support
|
43 |
|
44 | ## Docs
|
45 |
|
46 | - [Overview][docs_guides]
|
47 | - [API Docs][docs_api]
|
48 | - [Frequently Asked Questions (FAQ)][docs_faq]
|
49 |
|
50 | ## Usage
|
51 |
|
52 | Start by wrapping your component class with `Radium()`, like `export default Radium(Component)`, or `Component = Radium(Component)`, which works with classes, `createClass`, and stateless components (functions that take props and return a ReactElement). Then, write a style object as you normally would with inline styles, and add in styles for interactive states and media queries. Pass the style object to your component via `style={...}` and let Radium do the rest!
|
53 |
|
54 | ```jsx
|
55 | <Button kind="primary">Radium Button</Button>
|
56 | ```
|
57 |
|
58 | ```jsx
|
59 | import Radium from 'radium';
|
60 | import React from 'react';
|
61 | import color from 'color';
|
62 |
|
63 | class Button extends React.Component {
|
64 | static propTypes = {
|
65 | kind: PropTypes.oneOf(['primary', 'warning']).isRequired
|
66 | };
|
67 |
|
68 | render() {
|
69 | // Radium extends the style attribute to accept an array. It will merge
|
70 | // the styles in order. We use this feature here to apply the primary
|
71 | // or warning styles depending on the value of the `kind` prop. Since its
|
72 | // all just JavaScript, you can use whatever logic you want to decide which
|
73 | // styles are applied (props, state, context, etc).
|
74 | return (
|
75 | <button
|
76 | style={[
|
77 | styles.base,
|
78 | styles[this.props.kind]
|
79 | ]}>
|
80 | {this.props.children}
|
81 | </button>
|
82 | );
|
83 | }
|
84 | }
|
85 |
|
86 | Button = Radium(Button);
|
87 |
|
88 | // You can create your style objects dynamically or share them for
|
89 | // every instance of the component.
|
90 | var styles = {
|
91 | base: {
|
92 | color: '#fff',
|
93 |
|
94 | // Adding interactive state couldn't be easier! Add a special key to your
|
95 | // style object (:hover, :focus, :active, or @media) with the additional rules.
|
96 | ':hover': {
|
97 | background: color('#0074d9').lighten(0.2).hexString()
|
98 | }
|
99 | },
|
100 |
|
101 | primary: {
|
102 | background: '#0074D9'
|
103 | },
|
104 |
|
105 | warning: {
|
106 | background: '#FF4136'
|
107 | }
|
108 | };
|
109 | ```
|
110 |
|
111 | ## Importing Radium
|
112 |
|
113 | As of `v0.22.x`, Radium is built as an ECMAScript Modules-first project. We now have a `package.json:module` entry pointing to our library files with `import|export` statements instead of CommonJS `require`s. We still support CommonJS `require`s with a special `package.json:main` entry pointing to root `index.js` to smooth over this transition. The basic takeaways are:
|
114 |
|
115 | If you are using **ESM** with **webpack** or **`@std/esm`** with **Node.js**, imports like the following work fine without any gotchas:
|
116 |
|
117 | ```js
|
118 | import Radium from 'radium';
|
119 | import Radium, { Style } from 'radium';
|
120 | ```
|
121 |
|
122 | If you are using **CommonJS** with **Node.js** or **webpack@1** requires work like normal:
|
123 |
|
124 | ```js
|
125 | const Radium = require('radium');
|
126 | const { Style } = require('radium');
|
127 | ```
|
128 |
|
129 | If you are using **CommonJS** with **webpack@2+**, however, you must instead add `.default` to the root `Radium` object import:
|
130 |
|
131 | ```js
|
132 | const Radium = require('radium').default; // CHANGED: Must add `.default`
|
133 | const { Style } = require('radium'); // Works as per normal
|
134 | ```
|
135 |
|
136 | If you cannot change the `require` statements directly (say Radium is included from a different library your project depends on) you can manually tweak the Radium import in your project's webpack configuration with the following:
|
137 |
|
138 | ```js
|
139 | resolve: {
|
140 | alias: {
|
141 | radium: require.resolve("radium/index")
|
142 | }
|
143 | }
|
144 | ```
|
145 |
|
146 | which will allow `const Radium = require('radium');` to still work. The configuration effectively forces webpack to point to code from `package.json:main` (which points to `/index.js`) instead of what is in `package.json:module`.
|
147 |
|
148 | *Note:* Radium uses `Reflect` which is not supported in IE11. You will need to bring in a polyfill like [CoreJs](https://github.com/zloirock/core-js#ecmascript-reflect) in order to support <IE11.
|
149 |
|
150 | ## Examples
|
151 |
|
152 | To see the universal examples:
|
153 |
|
154 | ```
|
155 | npm install
|
156 | npm run universal
|
157 | ```
|
158 |
|
159 | To see local client-side only examples in action, do this:
|
160 |
|
161 | ```
|
162 | npm install
|
163 | npm run examples
|
164 | ```
|
165 |
|
166 | ## How does Radium work?
|
167 |
|
168 | Following is a short technical explanation of Radium's inner workings:
|
169 |
|
170 | - Wrap the `render` function
|
171 | - Recurse into the result of the original `render`
|
172 | - For each element:
|
173 | - Add handlers to props if interactive styles are specified, e.g. `onMouseEnter` for `:hover`, wrapping existing handlers if necessary
|
174 | - If any of the handlers are triggered, e.g. by hovering, Radium calls `setState` to update a Radium-specific field on the components state object
|
175 | - On re-render, resolve any interactive styles that apply, e.g. `:hover`, by looking up the element's key or ref in the Radium-specific state
|
176 |
|
177 | ## More with Radium
|
178 |
|
179 | You can find a list of other tools, components, and frameworks to help you build with Radium on our [wiki](https://github.com/FormidableLabs/radium/wiki). Contributions welcome!
|
180 |
|
181 | ## Contributing
|
182 |
|
183 | Please see [CONTRIBUTING](https://github.com/FormidableLabs/radium/blob/master/CONTRIBUTING.md)
|
184 |
|
185 | [trav_img]: https://api.travis-ci.org/FormidableLabs/radium.svg
|
186 | [trav_site]: https://travis-ci.org/FormidableLabs/radium
|
187 | [cov_img]: https://img.shields.io/coveralls/FormidableLabs/radium.svg
|
188 | [cov_site]: https://coveralls.io/r/FormidableLabs/radium
|
189 | [npm_img]: https://img.shields.io/npm/v/radium.svg
|
190 | [npm_site]: https://www.npmjs.org/package/radium
|
191 | [david_img]: https://img.shields.io/david/FormidableLabs/radium.svg
|
192 | [david_site]: https://david-dm.org/FormidableLabs/radium
|
193 | [size_img]: https://badges.herokuapp.com/size/npm/radium/dist/radium.min.js?gzip=true&label=gzipped
|
194 | [docs_guides]: https://github.com/FormidableLabs/radium/tree/master/docs/guides
|
195 | [docs_api]: https://github.com/FormidableLabs/radium/tree/master/docs/api
|
196 | [docs_faq]: https://github.com/FormidableLabs/radium/tree/master/docs/faq
|
197 | [appveyor_img]: https://ci.appveyor.com/api/projects/status/github/formidablelabs/radium?branch=master&svg=true
|
198 | [appveyor_site]: https://ci.appveyor.com/project/ryan-roemer/radium
|
199 |
|
\ | No newline at end of file |