# Getting Started
## Quick Start (CDN)
To try Material Components for the web with minimal setup, load the precompiled all-in-one CSS and JS bundles from unpkg:
```html
```
We also recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts. (Some of our examples implicitly use Material Icons.)
```html
```
Then include MDC markup...
```html
```
...and instantiate JavaScript:
```js
mdc.ripple.MDCRipple.attachTo(document.querySelector('.foo-button'));
```
## Installing Locally
Material Components for the web can be installed locally using npm. It is available as a single all-in-one package:
```
npm i material-components-web
```
...or as individual components:
```
npm i @material/button @material/ripple
```
Each package provides precompiled CSS and JS under its `dist` folder. The precompiled JS is converted to UMD format and is consumable directly by browsers or within any workflow that expects to consume ES5. Referencing `@material/foo` within a Node.js context will automatically reference the precompiled JS under `dist`.
However, for optimal results, we recommend consuming MDC Web's ES2015 modules and Sass directly. This is outlined in the steps below.
## Using MDC Web with Sass and ES2015
This section walks through how to [install MDC Web Node modules](https://www.npmjs.com/org/material), and bundle the Sass and JavaScript from those Node modules in your [webpack](https://webpack.js.org/) configuration.
You can also see the final code and result in the [Material Starter Kit](https://glitch.com/~material-starter-kit).
> Note: This guide assumes you have Node.js and npm installed locally.
### Step 1: Webpack with Sass
We’re going to use `webpack-dev-server` to demonstrate how webpack bundles our Sass and JavaScript. First, run `npm init` to create a `package.json` file. When complete, add the `start` property to the `scripts` section.
```json
{
"scripts": {
"start": "webpack serve"
}
}
```
You’ll need all of these Node dependencies:
- [webpack](https://www.npmjs.com/package/webpack): Bundles Sass and JavaScript
- [webpack-dev-server](https://www.npmjs.com/package/webpack-dev-server): Development server
- [sass-loader](https://www.npmjs.com/package/sass-loader): Webpack loader to preprocess Sass files
- [sass](https://www.npmjs.com/package/sass): Sass compiler
- [css-loader](https://www.npmjs.com/package/css-loader): Resolves CSS @import and url() paths
- [extract-loader](https://github.com/peerigon/extract-loader): Extracts the CSS into a `.css` file
- [file-loader](https://github.com/webpack-contrib/file-loader): Serves the `.css` file as a public URL
You can install all of them by running this command:
```
npm install --save-dev webpack webpack-cli webpack-dev-server css-loader sass-loader sass extract-loader file-loader
```
In order to demonstrate how webpack bundles our Sass, you’ll need an `index.html`. This HTML file needs to include CSS. The CSS is generated by sass-loader, which compiles Sass files into CSS. The CSS is extracted into a `.css` file by extract-loader. Create this simple “hello world” `index.html`:
```html
Hello World
```
And create a simple Sass file called `app.scss`:
```scss
body {
color: blue;
}
```
Then configure webpack to convert `app.scss` into `bundle.css`. For that you need a new `webpack.config.js` file:
```js
module.exports = [{
entry: './app.scss',
output: {
// This is necessary for webpack to compile
// But we never use style-bundle.js
filename: 'style-bundle.js',
},
module: {
rules: [
{
test: /\.scss$/,
use: [
{
loader: 'file-loader',
options: {
name: 'bundle.css',
},
},
{ loader: 'extract-loader' },
{ loader: 'css-loader' },
{
loader: 'sass-loader',
options: {
// Prefer Dart Sass
implementation: require('sass'),
// See https://github.com/webpack-contrib/sass-loader/issues/804
webpackImporter: false,
},
},
]
}
]
},
}];
```
To test your webpack configuration, run:
```
npm start
```
And open http://localhost:8080 in a browser. You should see a blue “Hello World”.
### Step 2: Include CSS for a component
Now that you have webpack configured to compile Sass into CSS, let's include the Sass files for the Material Design button. First, install the Node dependency:
```
npm install @material/button
```
We need to tell our `app.scss` to import the Sass files for `@material/button`. We can also use Sass mixins to customize the button. Replace your “hello world” version of `app.scss` with this code:
```scss
@use '@material/button/mdc-button';
@use '@material/button';
.foo-button {
@include button.container-fill-color(darksalmon);
}
```
We also need to configure sass-loader to understand the `@material` imports used by MDC Web. Update your `webpack.config.js` by changing `{ loader: 'sass-loader' }` to:
```js
{
loader: 'sass-loader',
options: {
// Prefer Dart Sass
implementation: require('sass'),
// See https://github.com/webpack-contrib/sass-loader/issues/804
webpackImporter: false,
sassOptions: {
includePaths: ['./node_modules']
},
}
}
```
> Note: Configuring `includePaths` should suffice for most cases where all MDC Web packages are kept up-to-date
> together. If you encounter problems compiling Sass due to nested `node_modules` directories, see the
> [Appendix](#appendix-configuring-a-sass-importer-for-nested-node_modules) below on how to configure a custom importer
> instead.
In order to add vendor-specific styles to the Sass files, we need to configure `autoprefixer` through PostCSS.
You'll need all of these Node dependencies:
- [autoprefixer](https://www.npmjs.com/package/autoprefixer): Parses CSS and adds vendor prefixes to CSS rules
- [postcss-loader](https://github.com/postcss/postcss-loader): Loader for Webpack used in conjunction with autoprefixer
You can install all of them by running this command:
```
npm install --save-dev autoprefixer postcss-loader
```
Add `autoprefixer` at the top of your `webpack.config.js`:
```js
const autoprefixer = require('autoprefixer');
```
Then add `postcss-loader`, using `autoprefixer` as a plugin:
```js
{ loader: 'extract-loader' },
{ loader: 'css-loader' },
{
loader: 'postcss-loader',
options: {
postcssOptions: {
plugins: [
autoprefixer()
]
}
}
},
{
loader: 'sass-loader',
options: {
sassOptions: {
includePaths: ['./node_modules']
},
// Prefer Dart Sass
implementation: require('sass'),
// See https://github.com/webpack-contrib/sass-loader/issues/804
webpackImporter: false,
}
},
```
`@material/button` has [documentation](../packages/mdc-button/README.md) about the required HTML for a button. Update your `index.html` to include the MDC Button markup, and add the `foo-button` class to the element:
```html
```
Now run `npm start` again and open http://localhost:8080. You should see a Material Design button!
### Step 3: Webpack with ES2015
We need to configure webpack to bundle ES2015 JavaScript into standard JavaScript, through [babel](https://babeljs.io). You’ll need all of these dependencies:
- [@babel/core](https://www.npmjs.com/package/@babel/core)
- [babel-loader](https://www.npmjs.com/package/babel-loader): Compiles JavaScript files using babel
- [@babel/preset-env](https://www.npmjs.com/package/@babel/preset-env): Preset for compiling es2015
You can install all of them by running this command:
```
npm install --save-dev @babel/core babel-loader @babel/preset-env
```
In order to demonstrate how webpack bundles our JavaScript, you’ll need to update `index.html` to include JavaScript. The JavaScript file is generated by babel-loader, which compiles ES2015 files into JavaScript. Add this script tag to `index.html` before the closing `
### Step 2: Include CSS for a component
Now that you have webpack configured to compile Sass into CSS, let's include the Sass files for the Material Design button. First, install the Node dependency:
```
npm install @material/button
```
We need to tell our `app.scss` to import the Sass files for `@material/button`. We can also use Sass mixins to customize the button. Replace your “hello world” version of `app.scss` with this code:
```scss
@use '@material/button/mdc-button';
@use '@material/button';
.foo-button {
@include button.container-fill-color(darksalmon);
}
```
We also need to configure sass-loader to understand the `@material` imports used by MDC Web. Update your `webpack.config.js` by changing `{ loader: 'sass-loader' }` to:
```js
{
loader: 'sass-loader',
options: {
// Prefer Dart Sass
implementation: require('sass'),
// See https://github.com/webpack-contrib/sass-loader/issues/804
webpackImporter: false,
sassOptions: {
includePaths: ['./node_modules']
},
}
}
```
> Note: Configuring `includePaths` should suffice for most cases where all MDC Web packages are kept up-to-date
> together. If you encounter problems compiling Sass due to nested `node_modules` directories, see the
> [Appendix](#appendix-configuring-a-sass-importer-for-nested-node_modules) below on how to configure a custom importer
> instead.
In order to add vendor-specific styles to the Sass files, we need to configure `autoprefixer` through PostCSS.
You'll need all of these Node dependencies:
- [autoprefixer](https://www.npmjs.com/package/autoprefixer): Parses CSS and adds vendor prefixes to CSS rules
- [postcss-loader](https://github.com/postcss/postcss-loader): Loader for Webpack used in conjunction with autoprefixer
You can install all of them by running this command:
```
npm install --save-dev autoprefixer postcss-loader
```
Add `autoprefixer` at the top of your `webpack.config.js`:
```js
const autoprefixer = require('autoprefixer');
```
Then add `postcss-loader`, using `autoprefixer` as a plugin:
```js
{ loader: 'extract-loader' },
{ loader: 'css-loader' },
{
loader: 'postcss-loader',
options: {
postcssOptions: {
plugins: [
autoprefixer()
]
}
}
},
{
loader: 'sass-loader',
options: {
sassOptions: {
includePaths: ['./node_modules']
},
// Prefer Dart Sass
implementation: require('sass'),
// See https://github.com/webpack-contrib/sass-loader/issues/804
webpackImporter: false,
}
},
```
`@material/button` has [documentation](../packages/mdc-button/README.md) about the required HTML for a button. Update your `index.html` to include the MDC Button markup, and add the `foo-button` class to the element:
```html
```
Now run `npm start` again and open http://localhost:8080. You should see a Material Design button!
### Step 3: Webpack with ES2015
We need to configure webpack to bundle ES2015 JavaScript into standard JavaScript, through [babel](https://babeljs.io). You’ll need all of these dependencies:
- [@babel/core](https://www.npmjs.com/package/@babel/core)
- [babel-loader](https://www.npmjs.com/package/babel-loader): Compiles JavaScript files using babel
- [@babel/preset-env](https://www.npmjs.com/package/@babel/preset-env): Preset for compiling es2015
You can install all of them by running this command:
```
npm install --save-dev @babel/core babel-loader @babel/preset-env
```
In order to demonstrate how webpack bundles our JavaScript, you’ll need to update `index.html` to include JavaScript. The JavaScript file is generated by babel-loader, which compiles ES2015 files into JavaScript. Add this script tag to `index.html` before the closing `