diff --git a/README.md b/README.md index eace46192..8d246cac2 100644 --- a/README.md +++ b/README.md @@ -18,29 +18,57 @@ Insert screenshot of a demo page, including a code snippet. > Note: This guide assumes you have npm installed locally. -To get started using one of the Material Web Components in your web application, simply: +The easiest way to try out the Material Web Components is to use one of these online tools: -1. Install each element you'd like to use: + * Runs in all supported browsers: StackBlitz, Glitch - ``` - npm install @material/mwc-button - ``` + * Runs in browsers with [JavaScript Modules](https://caniuse.com/#search=modules): [JSBin](http://jsbin.com/gitufet/edit?html,output), [CodePen](https://codepen.io/sorvell/pen/MGrZqp?editors=1000). + +Or you can also copy this HTML file into a local file and run it in any browser that supports JavaScript Modules. -1. Load the webcomponents polyfills (see the [webcomponents polyfill readme](https://github.com/webcomponents/webcomponentsjs/blob/v2/README.md) for more info). +When you're ready to use the Material Web Components in your web application: -1. Import the element: +1. Ensure the webcomponents polyfills are included in your HTML page - ```html - - ``` + - Install webcomponents polyfills -1. Use the element on the page: + ```npm i @webcomponents/webcomponentsjs``` - ```html - - ``` + - Add webcomponents polyfills to your HTML page + + `````` + + 1. Add one of the MWC elements to your project, for example for icon: + + ```npm i @material/mwc-icon``` + + 1. Import the element definition into your HTML page: + + `````` + + Or into your module script: + + ```import {Icon} from "@material/mwc-icon"``` + + 1. Create an instance of element in your HTML page, or via any framework that [supports rendering Custom Elements](https://custom-elements-everywhere.com/): + + ```sentiment_very_satisfied``` + + 1. Install the Polymer CLI: + + ```npm i -g polymer-cli@next``` + + 1. Run the development server and open a browser pointing to its URL: + + ```polymer serve``` + + > The Material Web Components are published on [npm](https://www.npmjs.com) 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](https://webpack.js.org/) and [Rollup](https://rollupjs.org/) can also be used to serve and/or bundle. + ## Contributing guide Below are instructions for setting up project development.