1 | #### Note
|
2 |
|
3 | For *how-to* questions and other non-issues,
|
4 | please use [StackOverflow](http://stackoverflow.com/questions/tagged/material-ui)
|
5 | instead of Github issues. There is a StackOverflow tag called "material-ui"
|
6 | that you can use to tag your questions.
|
7 |
|
8 | # [Material-UI](http://www.material-ui.com/)
|
9 |
|
10 | [![npm package](https://img.shields.io/npm/v/material-ui.svg?style=flat-square)](https://www.npmjs.org/package/material-ui)
|
11 | [![Build Status](https://travis-ci.org/callemall/material-ui.svg?branch=master)](https://travis-ci.org/callemall/material-ui)
|
12 | [![Gitter](https://img.shields.io/badge/gitter-join%20chat-f81a65.svg?style=flat-square)](https://gitter.im/callemall/material-ui?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
13 | [![Coverage Status](https://coveralls.io/repos/github/callemall/material-ui/badge.svg?branch=master)](https://coveralls.io/github/callemall/material-ui?branch=master)
|
14 |
|
15 | [![PeerDependencies](https://img.shields.io/david/peer/callemall/material-ui.svg?style=flat-square)](https://david-dm.org/callemall/material-ui#info=peerDependencies&view=list)
|
16 | [![Dependencies](https://img.shields.io/david/callemall/material-ui.svg?style=flat-square)](https://david-dm.org/callemall/material-ui)
|
17 | [![DevDependencies](https://img.shields.io/david/dev/callemall/material-ui.svg?style=flat-square)](https://david-dm.org/callemall/material-ui#info=devDependencies&view=list)
|
18 |
|
19 | Material-UI is a set of [React](http://facebook.github.io/react/) components that implement
|
20 | [Google's Material Design](https://www.google.com/design/spec/material-design/introduction.html)
|
21 | specification.
|
22 |
|
23 | Check out our [documentation site](http://www.material-ui.com/) for live examples.
|
24 | It's still a work in progress, but hopefully you can see where we're headed.
|
25 |
|
26 | **Recently Updated?** Please read the [changelog](https://github.com/callemall/material-ui/releases), this README and the documentation before posting an issue.
|
27 |
|
28 | ## Required Knowledge
|
29 |
|
30 | We recommend that you get to know [React](http://facebook.github.io/react/)
|
31 | before diving into material-ui. Material-UI is a set of React components,
|
32 | so understanding how React fits into web development is important.
|
33 |
|
34 | (If you're not familiar with Node, or with the concept of Single Page Applications (SPAs),
|
35 | head over to the [documentation website](http://material-ui.com/#/get-started/required-knowledge)
|
36 | for a quick introduction before you read on.)
|
37 |
|
38 | ## Installation
|
39 |
|
40 | Material-UI is available as an [npm package](https://www.npmjs.org/package/material-ui).
|
41 |
|
42 | **Stable channel**
|
43 | ```sh
|
44 | npm install material-ui
|
45 | ```
|
46 |
|
47 | **Pre-release channel**
|
48 | ```sh
|
49 | npm install material-ui@next
|
50 | ```
|
51 |
|
52 | Please note that `@next` will only point to pre-releases; to get the latest stable release use `@latest` instead.
|
53 |
|
54 |
|
55 | ### React-Tap-Event-Plugin
|
56 |
|
57 | (not needed for versions 0.19.0 and higher)
|
58 |
|
59 | Some components use
|
60 | [react-tap-event-plugin](https://github.com/zilverline/react-tap-event-plugin) to
|
61 | listen for touch events because onClick is not fast enough
|
62 | _This dependency is temporary and will eventually go away._ Until then,
|
63 | be sure to inject this plugin at the start of your app.
|
64 |
|
65 | ```js
|
66 | import injectTapEventPlugin from 'react-tap-event-plugin';
|
67 |
|
68 | // Needed for onTouchTap
|
69 | // http://stackoverflow.com/a/34015469/988941
|
70 | injectTapEventPlugin();
|
71 | ```
|
72 |
|
73 | ### Roboto Font
|
74 |
|
75 | Material-UI was designed with the [Roboto](http://www.google.com/fonts/specimen/Roboto)
|
76 | font in mind. So be sure to include it in your project. Here are
|
77 | [some instructions](http://www.google.com/fonts#UsePlace:use/Collection:Roboto:400,300,500)
|
78 | on how to do so.
|
79 |
|
80 | ## Usage
|
81 |
|
82 | Beginning with v0.15.0, Material-UI components require a theme to be provided. The quickest way to get up and running is by using the `MuiThemeProvider` to inject the theme into your application context. Following that, you can use any of the components as demonstrated in the documentation.
|
83 |
|
84 | Here is a quick example to get you started:
|
85 |
|
86 | **./App.js**
|
87 | ```jsx
|
88 | import React from 'react';
|
89 | import ReactDOM from 'react-dom';
|
90 | import MuiThemeProvider from 'material-ui/styles/MuiThemeProvider';
|
91 | import MyAwesomeReactComponent from './MyAwesomeReactComponent';
|
92 |
|
93 | const App = () => (
|
94 | <MuiThemeProvider>
|
95 | <MyAwesomeReactComponent />
|
96 | </MuiThemeProvider>
|
97 | );
|
98 |
|
99 | ReactDOM.render(
|
100 | <App />,
|
101 | document.getElementById('app')
|
102 | );
|
103 | ```
|
104 |
|
105 | **./MyAwesomeReactComponent.js**
|
106 | ```jsx
|
107 | import React from 'react';
|
108 | import RaisedButton from 'material-ui/RaisedButton';
|
109 |
|
110 | const MyAwesomeReactComponent = () => (
|
111 | <RaisedButton label="Default" />
|
112 | );
|
113 |
|
114 | export default MyAwesomeReactComponent;
|
115 | ```
|
116 |
|
117 | Please refer to each component's documentation page to see how they should be imported.
|
118 |
|
119 | ## Customization
|
120 |
|
121 | We have implemented a default theme to render all Material-UI components.
|
122 | Styling components to your liking is simple and hassle-free. This can be
|
123 | achieved in the following two ways:
|
124 |
|
125 | * [Use a custom theme to style components](http://material-ui.com/#/customization/themes)
|
126 | * [Override individual component styles via the `style` prop](http://www.material-ui.com/#/customization/styles)
|
127 |
|
128 | ## Examples
|
129 |
|
130 | There are 2 projects that you can look at to get started. They can be found in the
|
131 | [examples folder](https://github.com/callemall/material-ui/tree/master/examples).
|
132 | These projects are basic examples that show how to consume material-ui components
|
133 | in your own project. The first project uses [browserify](http://browserify.org/)
|
134 | for module bundling and [gulp](http://gulpjs.com/) for JS task automation,
|
135 | while the second project uses [webpack](http://webpack.github.io/) for module bundling and building.
|
136 |
|
137 | The source code for this documentation site is also included in the repository.
|
138 | This is a slightly more complex project that also uses webpack, and contains
|
139 | examples of every material-ui component. Check out the
|
140 | [docs folder](https://github.com/callemall/material-ui/tree/master/docs)
|
141 | for build instructions.
|
142 |
|
143 | ## Roadmap
|
144 |
|
145 | The future plans and high priority features and enhancements can be found
|
146 | in the [ROADMAP.md](https://github.com/mui-org/material-ui/blob/v0.x/ROADMAP.md) file.
|
147 |
|
148 | ## Contribute
|
149 |
|
150 | [Material-UI](http://www.material-ui.com/) came about from our love of
|
151 | [React](http://facebook.github.io/react/) and
|
152 | [Google's Material Design](https://www.google.com/design/spec/material-design/introduction.html).
|
153 | We're currently using it on a project at [Call-Em-All](https://www.call-em-all.com/Careers)
|
154 | and plan on adding to it and making it better. If you'd like to help,
|
155 | check out the [docs folder](https://github.com/callemall/material-ui/tree/master/docs).
|
156 | We'd greatly appreciate any [contribution](https://github.com/mui-org/material-ui/blob/v0.x/CONTRIBUTING.md)
|
157 | you make. :)
|
158 |
|
159 | ## Thanks
|
160 |
|
161 | [<img src="https://www.browserstack.com/images/mail/browserstack-logo-footer.png" width="120">](https://www.browserstack.com/)
|
162 |
|
163 | Thank you to [BrowserStack](https://www.browserstack.com/) for providing the infrastructure that allows us to test `material-ui` in real browsers.
|
164 |
|
165 | ## License
|
166 | This project is licensed under the terms of the
|
167 | [MIT license](https://github.com/mui-org/material-ui/blob/v0.x/LICENSE)
|