Material Web Components

Warning: These components are still a work in progress.

Material Web Components helps developers execute Material Design using web components.

Built on top of the Material Components Web project and LitElement, the Material Web Components enable a reliable development workflow to build beautiful and functional web projects.

Web Components can be seamlessly incorporated into a wide range of usage contexts. Whether you're already heavily invested in another framework or not, it's easy to incorporate Material Web Components into your site in a lightweight, idiomatic fashion.

Demos

Quick start

Note: This guide assumes you have npm installed locally.

The easiest way to try out the Material Web Components is to use one of these online tools:

Runs in all supported browsers: Glitch
Runs in browsers with JavaScript Modules: JSBin, CodePen.

Or you can also copy this HTML file into a local file and run it in any browser that supports JavaScript Modules.

When you're ready to use the Material Web Components in your web application:

Ensure the webcomponents polyfills are included in your HTML page
- Install webcomponents polyfills
  
  npm i @webcomponents/webcomponentsjs
- Add webcomponents polyfills to your HTML page
  
  <script src="@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
Add one of the MWC elements to your project, for example for icon:

npm i @material/mwc-icon
Import the element definition into your HTML page:

<script type="module" src="@material/mwc-icon/index.js"></script>

Or into your module script:

import {Icon} from "@material/mwc-icon"
Create an instance of element in your HTML page, or via any framework that supports rendering Custom Elements:

<mwc-icon>sentiment_very_satisfied</mwc-icon>
Install the Polymer CLI:

npm i -g polymer-cli
Run the development server and open a browser pointing to its URL:

polymer serve

The Material Web Components are published on npm using JavaScript Modules. This means it can take advantage of the standard native JavaScript module loader available in all current major browsers.

However, since the Material Web Components use npm convention to reference dependencies by name, a light transform to rewrite specifiers to URLs is required to get it to run in the browser. The polymer-cli's development server polymer serve automatically handles this transform.

Tools like WebPack and Rollup can also be used to serve and/or bundle.

Contributing guide

Below are instructions for setting up project development.

git clone this repo
install dependencies by running npm run bootstrap
to run a development server: npm run dev (view the demos by accessing <dev server url>/demos/index.html)
to run tests: npm run test

Rebuild CSS for components

Components define their css using SASS. The SASS output is built into a javascript module which exports the component's styling as a lit-html template.

To compile the component SASS run:

npm run update-styling

Useful Links

All Components
Demos
Contributing
Material.io (external site)
Material Design Guidelines (external site)

Browser Support

We officially support the last two versions of every major browser. Specifically, we test on the following browsers: