React Toolbox is a set of React components that implement Google’s Material Design specification. It’s powered by CSS Modules and harmoniously integrates with your webpack workflow, although you can use any other module bundler. You can take a tour through our documentation website and try the components live!

Note: This source code refers to the future version. To check the source for 1.x go to masterBranch. We are currently writing a migration guide so you can start working with 2.0-beta. X now!

Installation

React Toolbox can be installed as an npm package:

$ npm install --save react-toolboxCopy the code

Prerequisites

React Toolbox uses CSS Modules by default to import stylesheets written in SASS. In case you want to import the components already bundled with CSS, your module bundler should be able to require these SASS modules.

Although we recommend webpack, you are free to use whatever module bundler you want as long as it can compile and require SASS files located in your node_modules. If you are experiencing require errors, make sure your configuration satisfies this requirement.

Of course this is a set of React components so you should be familiar with React. If want to customize your components via themes, you may want to take a look to react-css-themr which is used by React Toolbox to make components easily themeable.

Basic usage

In this minimal example, we import a Button with styles already bundled:

import React from 'react';
import ReactDOM from 'react-dom';
import { Button } from 'react-toolbox/lib/button';

ReactDOM.render(
  <Button label="Hello World!" />.document.getElementById('app'));Copy the code

Take into account that any required style will be included in the final CSS so your final would include Button styles in this case. It’s more convenient to import components this way (or with raw imports) because if you require from the project root, every stylesheet of React Toolbox will be included, even if you don’t use it.

Bundled component

If you import from the index file, the imported component comes with all dependencies and themes already required and injected for you. This means that the CSS for each dependency will be bundled in your final CSS automatically and the component markup includes the classnames to be styled. For example:

import { AppBar } from 'react-toolbox/lib/app_bar';Copy the code

Customizing components

Every component accepts a theme property intended to provide a CSS Module import object that will be used by the component to assign local classnames to its DOM nodes. Therefore, each one implements a documented classname API. So if you want to customize a component, you just need to provide a theme object with the appropriated classname mapping.

If the component already has a theme injected, the properties you pass will be merged with the injected theme. In this way, you can add classnames to the nodes of a specific component and use them to add or to override styles. For example, if you want to customize the AppBar to be purple:

import React from 'react';
import { AppBar } from 'react-toolbox/lib/app_bar';
import theme from './PurpleAppBar.scss';

const PurpleAppBar = (props) = > (
  <AppBar {.props} theme={theme} />
);

export default PurpleAppBar;
Copy the code

.appBar {
  background-color: # 800080;
}Copy the code

In this case we are adding styles to an AppBar component that already has some styles injected. It works because the component background by default has the same priority as the one we added. There will be cases where the original rule is more restrictive. For those cases you would need to boost priority using the same restrictions as in the original stylesheet. Feel free to take a look into the original themes or just check the selectors you want to override in DevTools.

If the component has no styles injected, you should provide a theme object implementing the full API. You are free to require the CSS Module you want but take into account that every classname is there for a reason. You can either provide a theme via prop or via context as we will see later.

Theming

You can afford theming in multiple ways. First of all, you have to understand that React Toolbox stylesheets are written in SASS and configured using the config files we saw earlier. Also you may want to check colors and globals files to get an overview on the variables you have to override to get the results you want.

In most scenarios you can get more customized themes by overriding those variables and compiling stylesheets with them. For example, you can create a _theme.scss SASS file:

@import "~react-toolbox/lib/colors";

$color-primary: $palette-blue-500;
$color-primary-dark: $palette-blue-700;Copy the code

This file should be prepended to each stylesheet compilation which can be achieved in multiple ways.

Using SASS imports and props

Remember that you can import components without styles and provide those styles using the theme property. For example, a theme for a button customized with the previous theme file would be like:

@import "theme.scss";
@import "~react-toolbox/lib/button/theme";Copy the code

Then, when you use a button, you can inject the appropriate theme:

import { Button } from 'react-toolbox/lib/button/Button';
import buttonTheme from './theme/button.scss';

const ThemedButton = (props) = > (
  <Button theme={buttonTheme}  {.props} />
);

export default ThemedButton;Copy the code

With this technique you have to create wrappers for every component, and this is not cool at all… but don’t worry, we can provide the theme via context to avoid this.

Roboto Font and Material Design Icons

React Toolbox assumes that you are importing Roboto Font and Material Design Icons.

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.

Server Side Rendering

The only requirement for SSR is to be able to require ES6 and CSS Modules in the backend. To make it possible you can check projects like CSS Modules register hook or Webpack Isomorphic tools. Also, make sure you can import from node_modules.

Examples

For now we have a repository example demonstrating configuration and some basic customization. For now it’s not using SSR rendering but it shouldn’t be difficult to implement an example so it will come soon. Feel free to PR your example project or to add some use cases to the repository.

TypeScript

TypeScript external module definition files are included, and should not require any manual steps to utilize. They will be picked up by the TypeScript compiler when importing from the npm package.

Note that to comply with the official recommendation for npm typings, a triple-slash reference to react.d.ts is NOT included. You will need to reference react.d.ts somewhere in your project.

Authors and Contributors

The project is being initially developed and maintained by Javier Velasco and Javier Jiménez and the contribution scene is just getting warm. We want to create reference components so any contribution is very welcome.

To work in the project you’d need a node version supporting ES6 syntax. Although the project is built using Babel we use some ES6 features in the development server. Also, The package has been tested with node 4.2.1. Consider using NVM or N to handle different node versions!

To start the documentation site locally, you’ll need to install the dependencies from both the main package and the docs subproject:

$ git clone https://github.com/react-toolbox/react-toolbox.git
$ cd react-toolbox/
$ npm install
$ cd docs/
$ npm install
$ npm start
Copy the code

Local documentation will then be available at http://localhost:8081/.

Extensions

We don’t officially support components that are not covered by Google Material Design. If you want to implement some complementary component feel free to open a PR adding your a link in this section. For now you can check on github: react-toolbox-additions and on npm: react-toolbox-additions.

Support

Sponsors

Become a sponsor and get your logo on our README on Github with a link to your site. [Become a sponsor]

License

This project is licensed under the terms of the MIT license.