2019-09-27 00:40:51 +03:00
# Material Web Components [](https://travis-ci.org/material-components/material-components-web-components)
> IMPORTANT: The Material Web Components are a work in progress and subject to major changes until 1.0 release.
The Material Web Components (MWC) are a collection of [Web Components ](https://developer.mozilla.org/en-US/docs/Web/Web_Components ) maintained by Google that implement [Material Design ](https://material.io/design/ ).
## Components
| Component | Status | Issues
| ----------| ------ | ------
| [`<mwc-button>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/button ) | [](https://www.npmjs.com/package/@material/mwc-button) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Button%22 )
| `<mwc-bottom-app-bar>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/298 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Bottom+App+Bar%22 )
| `<mwc-card>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/231 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Card%22 )
| [`<mwc-checkbox>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/checkbox ) | [](https://www.npmjs.com/package/@material/mwc-fab) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Checkbox%22 )
| `<mwc-chip>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/418 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Chip%22 )
| `<mwc-circular-progress>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/500 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Circular+Progress%22 )
| `<mwc-data-table>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/386 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Data+Table%22 )
| [`<mwc-dialog>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/dialog ) | [](https://www.npmjs.com/package/@material/mwc-dialog) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Dialog%22 )
2019-10-01 22:24:18 +03:00
| [`<mwc-drawer>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/drawer ) | [](https://www.npmjs.com/package/@material/mwc-drawer) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Drawer%22 )
2019-09-27 00:40:51 +03:00
| [`<mwc-fab>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/fab ) | [](https://www.npmjs.com/package/@material/mwc-fab) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Fab%22 )
| [`<mwc-formfield>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/formfield ) | [](https://www.npmjs.com/package/@material/mwc-formfield) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Form+Field%22 )
| [`<mwc-icon-button-toggle>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/icon-button-toggle ) | [](https://www.npmjs.com/package/@material/mwc-icon-button-toggle) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Icon+Button%22 )
| [`<mwc-icon-button>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/icon-button ) | [](https://www.npmjs.com/package/@material/mwc-icon-button) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Icon+Button%22 )
| [`<mwc-icon>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/icon ) | [](https://www.npmjs.com/package/@material/mwc-icon) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Icon%22 )
2019-10-20 03:38:40 +03:00
| [`<mwc-linear-progress>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/linear-progress ) | [](https://www.npmjs.com/package/@material/mwc-linear-progress) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Linear+Progress%22 )
2019-09-27 00:40:51 +03:00
| `<mwc-list>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/190 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+List%22 )
2019-10-02 20:16:47 +03:00
| `<mwc-menu>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/212 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aopen+is%3Aissue+label%3A%22Component%3A+Menu%22 )
2019-09-27 00:40:51 +03:00
| [`<mwc-radio>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/radio ) | [](https://www.npmjs.com/package/@material/mwc-radio) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Radio%22 )
| `<mwc-select>` | [*Planned* ](https://github.com/material-components/material-components-web-components/issues/315 ) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Select%22 )
| [`<mwc-slider>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/slider ) | [](https://www.npmjs.com/package/@material/mwc-slider) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Slider%22 )
| [`<mwc-snackbar>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/snackbar ) | [](https://www.npmjs.com/package/@material/mwc-snackbar) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Snackbar%22 )
| [`<mwc-switch>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/switch ) | [](https://www.npmjs.com/package/@material/mwc-switch) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Switch%22 )
| [`<mwc-tab-bar>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/tab-bar ) | [](https://www.npmjs.com/package/@material/mwc-tab-bar) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Tab%22 )
| [`<mwc-tab>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/tab ) | [](https://www.npmjs.com/package/@material/mwc-tab) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Tab%22 )
| [`<mwc-textarea>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/textarea ) | [](https://www.npmjs.com/package/@material/mwc-textarea) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Text+Field%22 )
| [`<mwc-textfield>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/textfield ) | [](https://www.npmjs.com/package/@material/mwc-textfield) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Text+Field%22 )
| [`<mwc-top-app-bar-fixed>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/top-app-bar-fixed ) | [](https://www.npmjs.com/package/@material/mwc-top-app-bar-fixed) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Top+App+bar%22 )
| [`<mwc-top-app-bar>` ](https://github.com/material-components/material-components-web-components/tree/master/packages/top-app-bar ) | [](https://www.npmjs.com/package/@material/mwc-top-app-bar) | [*Issues* ](https://github.com/material-components/material-components-web-components/issues?q=is%3Aissue+is%3Aopen+label%3A%22Component%3A+Top+App+Bar%22 )
2018-04-26 05:20:55 +03:00
## Quick start
2019-09-27 00:40:51 +03:00
#### 1) Install
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
Install a component from NPM:
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
```sh
npm install @material/mwc -button @webcomponents/webcomponentsjs
```
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
#### 2) Write HTML and JavaScript
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
Import the component's JavaScript module, use the component in your HTML, and control it with JavaScript, just like you would with a built-in element such as `<button>` :
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
```html
<!doctype html>
< html >
< head >
< meta charset = "utf-8" >
< title > My Example App< / title >
<!-- Add support for Web Components to older browsers. -->
< script src = "./node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" > < / script >
<!-- Your application must load the Roboto and Material Icons fonts. -->
< link href = "https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel = "stylesheet" >
< link href = "https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel = "stylesheet" >
< / head >
< body >
<!-- Use Web Components in your HTML like regular built - in elements. -->
< mwc-button id = "myButton" label = "Click Me!" raised > < / mwc-button >
<!-- The Material Web Components use standard JavaScript modules. -->
< script type = "module" >
// Importing this module registers < mwc-button > as an element that you
// can use in this page.
//
// Note this import is a bare module specifier, so it must be converted
// to a path using a server such as es-dev-server.
import '@material/mwc-button';
// Standard DOM APIs work with Web Components just like they do for
// built-in elements.
const button = document.querySelector('#myButton');
button.addEventListener('click', () => {
alert('You clicked!');
});
< / script >
< / body >
< / html >
```
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
#### 3) Serve
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
Serve your HTML with any server or build process that supports *bare module specifier resolution* (see next section):
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
```sh
npm install -g es-dev-server
es-dev-server --node-resolve
```
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
## Bare module specifiers
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
The Material Web Components are published as standard [JavaScript modules ](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules ) that use *bare module specifiers* . Bare module specifiers are not yet supported by browsers, so it is necessary to use a tool that transforms
them to a *path* (for example from `@material/mwc-button` to `./node_modules/@material/mwc-button/mwc-button.js` ).
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
Two great choices for tools that do this are:
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
- During local development, use open-wc's [`es-dev-server` ](https://open-wc.org/developing/es-dev-server.html ) with the `--node-resolve` flag.
- For your production deployment, build your application with [Rollup ](https://rollupjs.org/guide/en/ ) using the [`rollup-plugin-node-resolve` ](https://github.com/rollup/rollup-plugin-node-resolve ) plugin.
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
## Fonts
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
Most applications should include the following tags in their main HTML file to ensure that text and icons
render correctly:
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
```html
< link href = "https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel = "stylesheet" >
< link href = "https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel = "stylesheet" >
```
2018-05-08 23:28:33 +03:00
2019-09-27 00:40:51 +03:00
The Material Web Components default to using the [Roboto ](https://fonts.google.com/specimen/Roboto ) font for text, and the [Material Icons ](https://google.github.io/material-design-icons/ ) font for icons. These fonts
are *not* automatically loaded, so it is the application's responsiblity to ensure that they are loaded.
2018-05-09 01:55:53 +03:00
2019-09-27 00:40:51 +03:00
Note that if you load the Material Icons font in a different way to the recommendation shown above, be sure to include [`font-display: block` ](https://google.github.io/material-design-icons/ ) in your `@font-face` CSS rule. This prevents icons from initially displaying their raw *ligature* text before the font has loaded. The `<link>` tag recommended above automaticaly handles this setting.
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
## Supporting older browsers
2019-08-23 22:49:39 +03:00
2019-09-27 00:40:51 +03:00
The Material Web Components use modern browser features that are natively supported in the latest versions of Chrome, Safari, and Firefox. Edge, IE11, and some older versions of other browsers are also supported, but they require additional build steps and polyfills.
2019-08-23 22:49:39 +03:00
2019-09-27 00:40:51 +03:00
< table >
< tr >
< th > < i > Feature< / i > < / th >
< th > < img src = "images/chrome.png" width = "20px" height = "20px" > < br > Chrome< / th >
< th > < img src = "images/safari.png" width = "20px" height = "20px" > < br > Safari< / th >
< th > < img src = "images/firefox.png" width = "19px" height = "20px" > < br > Firefox< / th >
< th > < img src = "images/edge.png" width = "19px" height = "20px" > < br > Edge< / th >
< th > < img src = "images/ie.png" width = "20px" height = "20px" > < br > IE11< / th >
< / tr >
< tr >
< td > < a href = "https://developer.mozilla.org/en-US/docs/Web/Web_Components" > Web Components< / a > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td class = "ie11" > < img src = "images/orange-check.png" width = "20px" height = "20px" class = "check" alt = "Polyfill" > < a href = "#web-components" > *< / a > < / td >
< td class = "ie11" > < img src = "images/orange-check.png" width = "20px" height = "20px" class = "check" alt = "Polyfill" > < a href = "#web-components" > *< / a > < / td >
< / tr >
< tr >
< td > < a href = "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules" > Modules< / a > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td class = "ie11" > < img src = "images/orange-check.png" width = "20px" height = "20px" class = "check" alt = "Transform" > < a href = "#modules" > *< / a > < / td >
< td class = "ie11" > < img src = "images/orange-check.png" width = "20px" height = "20px" class = "check" alt = "Transform" > < a href = "#modules" > *< / a > < / td >
< / tr >
< tr >
< td > < a href = "https://developers.google.com/web/shows/ttt/series-2/es2015" > ES2015< / a > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td > < img src = "images/check-green.png" width = "20px" height = "20px" class = "check" alt = "Yes" > < / td >
< td class = "ie11" > < img src = "images/orange-check.png" width = "20px" height = "20px" class = "check" alt = "Transpile" > < a href = "#es2015" > *< / a > < / td >
< / tr >
< / table >
2019-08-23 22:49:39 +03:00
2019-09-27 00:40:51 +03:00
#### Web Components
2019-08-23 22:49:39 +03:00
2019-09-27 00:40:51 +03:00
To support Web Components in Edge, IE11, and other older browsers, install the [Web Components Polyfills ](https://github.com/webcomponents/polyfills/tree/master/packages/webcomponentsjs ):
2019-08-23 22:49:39 +03:00
2019-09-27 00:40:51 +03:00
```sh
npm install @webcomponents/webcomponentsjs
```
2019-08-22 03:55:51 +03:00
2019-09-27 00:40:51 +03:00
And include the `webcomponents-loader.js` script in your HTML, which detects when polyfills are needed and loads them automatically:
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
```html
<!-- Add support for Web Components to Edge and IE11. -->
< script src = "node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" > < / script >
```
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
#### Modules
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
To support Edge, IE11, or other older browsers that do not support JavaScript modules, you must transform JavaScript modules to classic JavaScript scripts. [Rollup ](https://rollupjs.org/guide/en/ ) is a popular tool that can consume JavaScript modules and produce a number of other formats, such as AMD. Be sure to use the [`rollup-plugin-node-resolve` ](https://github.com/rollup/rollup-plugin-node-resolve ) plugin to resolve *bare module specifiers* , as mentioned [above ](#bare-module-specifiers ).
2018-10-04 22:27:19 +03:00
2019-09-27 00:40:51 +03:00
#### ES2015
2018-10-04 22:27:19 +03:00
2019-09-27 00:40:51 +03:00
If you support IE11 or other older browsers that do not support the latest version of JavaScript, you must *transpile* your application to ES5. [Babel ](https://babeljs.io/ ) is a popular tool that does this. You can integrate Babel transpilation into a Rollup configuration using [rollup-plugin-babel ](https://github.com/rollup/rollup-plugin-babel ).
2018-10-04 22:27:19 +03:00
2019-09-27 00:40:51 +03:00
## Contributing
2018-10-04 22:27:19 +03:00
2019-09-27 00:40:51 +03:00
Clone and setup the repo:
2018-10-04 22:27:19 +03:00
2019-09-27 00:40:51 +03:00
```sh
git clone git@github.com:material-components/material-components-web-components.git mwc
cd mwc
npm install
npm run build
```
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
View the demos:
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
```sh
npm run dev
http://127.0.0.1:80801/demos
```
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
Run all tests:
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
```sh
npm run test
```
2018-04-26 05:20:55 +03:00
2019-09-27 00:40:51 +03:00
Run tests for a specific component:
```sh
npm run test -- --packages=mwc-button
```
