|
1 | 1 | # Installation, usage and customization |
2 | 2 |
|
3 | | -React Toolbox is a set of [React](http://facebook.github.io/react/) components that implement [Google's Material Design specification](https://www.google.com/design/spec/material-design/introduction.html). It's powered by [CSS Modules](https://github.com/css-modules/css-modules) and harmoniously integrates with your [Webpack](http://webpack.github.io/) workflow. You can take a tour through our documentation website and try the components live! |
| 3 | +React Toolbox is a set of [React](http://facebook.github.io/react/) components that implement [Google's Material Design specification](https://www.google.com/design/spec/material-design/introduction.html). It's powered by [CSS Modules](https://github.com/css-modules/css-modules) and harmoniously integrates with your [webpack](http://webpack.github.io/) workflow. You can take a tour through our documentation website and try the components live! |
4 | 4 |
|
5 | 5 | ## Installation |
6 | 6 |
|
7 | | -React Toolbox can be installed as an [npm package](https://www.npmjs.org/package/react-toolbox); |
| 7 | +React Toolbox can be installed as an [npm package](https://www.npmjs.org/package/react-toolbox): |
8 | 8 |
|
9 | | -``` |
| 9 | +```bash |
10 | 10 | npm install --save react-toolbox |
11 | 11 | ``` |
12 | 12 |
|
13 | | -## Usage |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +React Toolbox uses [CSS Modules](https://github.com/css-modules/css-modules) and [SASS](http://sass-lang.com/) to provide default stylesheets. If you want to import components bundled with stylesheets, your module bundler should be able to require SASS modules. You can use whatever module bundler you want as long as it can require SASS files from `node_modules`, but we recommend [webpack](). If you are experiencing require errors, make sure your configuration satisfies the requirements. |
| 16 | + |
| 17 | +Of course this is a set of React components so you should be familiar with [React](). If you are willing to customize your components via themes, you may want to take a look to [react-css-themr]() which is used to make styling easier. |
14 | 18 |
|
15 | | -Although there are other ways to use React Toolbox, the recommended way is to create a Webpack workflow with [Babel Loader](https://github.com/babel/babel-loader), [CSS Loader](https://github.com/webpack/css-loader) and [SASS Loader](https://github.com/jtangelder/sass-loader). A good starting point is [React Hot Webpack Boilerplate](https://github.com/gaearon/react-hot-boilerplate). |
| 19 | +## Basic usage |
16 | 20 |
|
17 | | -Once you have the workflow ready, you can just require and use the components: |
| 21 | +The minimal example requires a `Button` bundled with styles: |
18 | 22 |
|
19 | | -```jsx |
| 23 | +``` |
20 | 24 | import React from 'react'; |
21 | | -import Button from 'react-toolbox/lib/button'; |
| 25 | +import ReactDOM from 'react-dom'; |
| 26 | +import { Button } from 'react-toolbox/lib/button'; |
22 | 27 |
|
23 | | -const CustomButton = () => ( |
24 | | - <Button label="Hello world" raised accent /> |
| 28 | +ReactDOM.render( |
| 29 | + <Button label="Hello World!" />, |
| 30 | + document.getElementById('app') |
25 | 31 | ); |
26 | | - |
27 | | -export default CustomButton; |
28 | 32 | ``` |
29 | 33 |
|
30 | | -The previous code creates a React button component based on React toolbox button. It's important to notice that requiring a module from the exposed root of the package will import the **SASS** of the component. |
| 34 | +Take into account that any required style will be bundled in the final CSS so you probably would want to require components one by one instead of requiring directly from the root index. |
31 | 35 |
|
32 | | -## Roboto Font and Material Design Icons |
| 36 | +## Importing components |
33 | 37 |
|
34 | | -React Toolbox assumes that you are importing [Roboto Font](https://www.google.com/fonts/specimen/Roboto) and [Material Design Icons](https://www.google.com/design/icons/). |
| 38 | +First let's take a look on how the components are structured in the project. The [components](https://github.com/react-toolbox/react-toolbox/tree/dev/components) folder contains a folder for each component or set of related components. For example, the `app_bar`: |
35 | 39 |
|
36 | | -In order to import the fonts for you, we'd need to include them in the CSS which is considered a bad practice. If you are not including them in your app to the linked sites and follow the instructions. |
| 40 | +``` |
| 41 | + |- /app_bar |
| 42 | + |---- AppBar.js |
| 43 | + |---- _config.scss |
| 44 | + |---- index.js |
| 45 | + |---- readme.md |
| 46 | + |---- theme.scss |
| 47 | +``` |
| 48 | + |
| 49 | +There you can see a component definition file, a readme, an index file, a theme stylesheet and a configuration file holding the SASS variables to configure the stylesheet. Depending on whether you want the styles to be directly bundled or not, you can import components in two different ways: |
| 50 | + |
| 51 | +- **Bundled component**: the component requires the corresponding `theme.scss` for you so it will be included in the final bundle. Also, the local classnames will be injected in the component automatically. To import a bundled component you have to require from the `index.js` file. For example: `import {AppBar} from 'react-toolbox/lib/app_bar'`. |
| 52 | + |
| 53 | +- **Raw component**: the component is required alone, without any CSS. In this case you are responsible from providing a theme. To import a raw component you have to require directly from the component definition. For example: `import AppBar from 'react-toolbox/lib/app_bar/AppBar'`. |
37 | 54 |
|
38 | 55 | ## Customization |
39 | 56 |
|
40 | | -Since React Toolbox styles are written in CSS it's pretty easy to customize your components. We have several ways: |
| 57 | +Since you can import raw components and then inject a theme via props or context, you can use whatever you want to provide styles. We give you some SASS stylesheets but you can configure them at import time or even port them to CSS Next or whatever. Furthermore, you can provide extra theming classes that will be mixed in the component so you can even target DOM elements in subcomponents from a parent. Let's see some examples. |
| 58 | + |
| 59 | +### Customization via SASS Loader |
41 | 60 |
|
42 | | -### Via React Toolbox Loader |
| 61 | +Every component in React Toolbox has a `_config.scss` partial and [some parent partials](https://github.com/react-toolbox/react-toolbox/tree/dev/components) defining configuration variables that are used in each `theme.scss`. Since all variables are defined as `!default`, you can prepend variable overrides with a custom `theme.scss` file to each SASS stylesheet required in the project. |
43 | 62 |
|
44 | | -Thanks to the power of SASS, all components in React Toolbox are configured from a variables file. The best way to customize your build is to create a custom configuration SASS file overriding configuration variables like colors or sizes. |
| 63 | +If you are importing bundled components, you can use something like [sass-loader](https://github.com/jtangelder/sass-loader) to prepend your custom configuration files to every sass stylesheet by using the `data` option. For example, in your webpack config: |
45 | 64 |
|
46 | | -With [toolbox-loader](https://github.com/react-toolbox/toolbox-loader) you can tell webpack where your configuration file is and it will prepend your config to each SASS build. This will result in your customized CSS for React Toolbox Components. For now you can browse the configuration files and override what you want. |
| 65 | +```js |
| 66 | +sassLoader: { |
| 67 | + data: '@import "' + path.resolve(__dirname, 'theme/_theme.scss') + '";' |
| 68 | +} |
| 69 | +``` |
47 | 70 |
|
48 | | -### Via `className` property |
| 71 | +### Customization via Theme Property |
49 | 72 |
|
50 | | -Generally each component will have a `className` prop so that you can apply a class name to the root node of the resulting markup. All markup is styled with the lowest specificity level so you can just nest one level in your CSS and the result will be applied. Consider this example: |
| 73 | +Every component in React Toolbox have a **classname API** that can be browsed from the documentation. Also, they accept a `theme` property intended to provide a [CSS Module import object](https://github.com/css-modules/css-modules) that will be used by the component to assign local classnames to its DOM nodes. |
51 | 74 |
|
52 | | -```jsx |
53 | | -const CustomButton = () => ( |
54 | | - <Button className='customized' label='Custom button' /> |
| 75 | +React Toolbox uses [react-css-themr](github.com/javivelasco/react-css-themr) to make theming easier. Feel free to take a look to the documentation to learn how you can use themes for the components. For example, imagine you want to create a green success button whose icons are red: |
| 76 | + |
| 77 | +``` |
| 78 | +// SuccessButton.js |
| 79 | +import { Button } from 'react-toolbox/lib/button'; |
| 80 | +import successTheme from './success-theme.scss'; |
| 81 | +
|
| 82 | +const SuccessButton = (props) => ( |
| 83 | + <Button theme={successButtonTheme} {...props} /> |
55 | 84 | ); |
| 85 | +
|
| 86 | +export default SuccessButton; |
56 | 87 | ``` |
57 | 88 |
|
58 | | -If you browse the resulting markup you will see *data attributes* like `data-role="label"` which can be used to style components without using tag name selectors. You can now write your CSS: |
| 89 | +``` |
| 90 | +// success-theme.scss |
| 91 | +.primary { |
| 92 | + background: green; |
| 93 | +} |
59 | 94 |
|
60 | | -```css |
61 | | -.customized > [data-react-toolbox="label"] { |
62 | | - color: green; |
63 | | - font-weight: bold; |
| 95 | +.icon { |
| 96 | + color: red |
64 | 97 | } |
65 | 98 | ``` |
| 99 | + |
| 100 | +The given classes will be added to the component and, since they are defined *after* the original CSS they would take priority. Note that you can also boost priority by assigning a `className`. Check more examples at [react-css-themr](www.github.com/javivelasco/react-css-themr) documentation. |
| 101 | + |
| 102 | +### Customization via Theme Context |
| 103 | + |
| 104 | +Alternatively, you can provide CSS Modules object to React Toolbox components using context. This is useful in case you want to create a custom theme without creating wrappers for each raw component. To use this customization you need to install react-css-themr and then use the **theme keys** specified in each component documentation. For example: |
| 105 | + |
| 106 | +``` |
| 107 | +import React from 'react'; |
| 108 | +import ReactDOM from 'react-dom'; |
| 109 | +import { ThemeProvider } from 'react-css-themr'; |
| 110 | +import Button from 'react-toolbox/lib/button/Button'; |
| 111 | +import App from './App.js'; |
| 112 | +
|
| 113 | +const theme = { |
| 114 | + RTButton: require('./theme/button-style') |
| 115 | +}; |
| 116 | +
|
| 117 | +const ThemedApp = (children) => ( |
| 118 | + <ThemeProvider theme={theme}> |
| 119 | + <App /> |
| 120 | + </ThemeProvider> |
| 121 | +) |
| 122 | +
|
| 123 | +ReactDOM.render(<ThemedApp />, document.getElementById('app')); |
| 124 | +``` |
| 125 | + |
| 126 | +## Roboto Font and Material Design Icons |
| 127 | + |
| 128 | +React Toolbox assumes that you are importing [Roboto Font](https://www.google.com/fonts/specimen/Roboto) and [Material Design Icons](https://www.google.com/design/icons/). |
| 129 | + |
| 130 | +In order to import the fonts for you, we'd need to include them in the CSS which is considered a bad practice. If you are not including them in your app, go to the linked sites and follow the instructions. |
0 commit comments