Skip to content

docs(Getting Started): Updated material Getting Started guide to use install schematics and simplify the overall process #16654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Aug 22, 2019
Merged

docs(Getting Started): Updated material Getting Started guide to use install schematics and simplify the overall process #16654

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c2d67be
docs: rewrite getting started guide to use CLI schematics
manughub Jul 31, 2019
452cb59
docs(Getting Started): Moving HammerJS install to appendix
manughub Aug 22, 2019
60efb40
docs(Getting Started): Moving HammerJS install to appendix
manughub Aug 22, 2019
22c0fa4
docs(Getting Started): Moving HammerJS install to appendix
manughub Aug 22, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 51 additions & 151 deletions guides/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,196 +1,96 @@
For help getting started with a new Angular app, check out the
[Angular CLI](https://cli.angular.io/).
# Getting Started with Angular Material

For existing apps, follow these steps to begin using Angular Material.
This guide explains how to setup your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.

### Step 1: Install Angular Material, Angular CDK and Angular Animations
### New to Angular ?

You can use either the npm or yarn command-line tool to install packages. Use whichever is appropriate for your project in the examples below.
If you are new to Angular or getting started with a new Angular application, see [Angular's full Getting Started Guide](https://angular.io/start) and [Setting up your environment](https://angular.io/guide/setup-local).

#### NPM
```bash
npm install --save @angular/material @angular/cdk @angular/animations
```
#### Yarn
```bash
yarn add @angular/material @angular/cdk @angular/animations
```
For existing applications, follow the steps below to begin using Angular Material:


#### Alternative 1: Snapshot Build
### Step 1: Install Angular Material npm packages

A snapshot build with the latest changes from master is also available. Note that this snapshot
build should not be considered stable and may break between releases.
Use the Angular CLI's install [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:

#### NPM
```bash
npm install --save angular/material2-builds angular/cdk-builds angular/animations-builds
ng add @angular/material
```

#### Yarn
```bash
yarn add angular/material2-builds angular/cdk-builds angular/animations-builds
```
#### Alternative 2: Angular Devkit 6+
The `ng add` command will install Angular Material, the [Component Dev Kit (CDK)](https://material.angular.io/cdk/categories), [Angular Animations](https://angular.io/guide/animations) and ask you the following questions to determine which features to include:

Using the Angular CLI `ng add` command will update your Angular project with the correct dependencies, perform configuration changes and execute initialization code.
1. Choose a prebuilt theme name, or "custom" for a custom theme:

```bash
ng add @angular/material
```
You can choose from [prebuilt material design themes](https://material.angular.io/guide/theming#using-a-pre-built-theme) or set up an extensible [custom theme](https://material.angular.io/guide/theming#defining-a-custom-theme).

### Step 2: Configure animations
2. Set up HammerJS for gesture recognition:

Once the animations package is installed, import `BrowserAnimationsModule` into your application to enable animations support.
[HammerJS](http://hammerjs.github.io/) provides gesture recognition capabilities required by some components (`mat-slide-toggle`, `mat-slider`, `matToolTip`).

```ts
import {BrowserAnimationsModule} from '@angular/platform-browser/animations';
Please note, if you choose not to install HammerJS it can be installed later (see Appendix).

@NgModule({
...
imports: [BrowserAnimationsModule],
...
})
export class PizzaPartyAppModule { }
```
3. Set up browser animations for Angular Material:

Alternatively, you can disable animations by importing `NoopAnimationsModule`.
Importing the [`BrowserAnimationsModule`](https://angular.io/api/platform-browser/animations/BrowserAnimationsModule) into your application enables Angular's [animation system](https://angular.io/guide/animations). Declining this will disable most of Angular Material's animations.

```ts
import {NoopAnimationsModule} from '@angular/platform-browser/animations';
The `ng add` command will additionally perform the following configurations:

@NgModule({
...
imports: [NoopAnimationsModule],
...
})
export class PizzaPartyAppModule { }
```
* Add project dependencies to `package.json`
* Add the Roboto font to your `index.html`
* Add the Material Design icon font to your `index.html`
* Add a few global CSS styles to:
* Remove margins from `body`
* Set `height: 100%` on `html` and `body`
* Set Roboto as the default application font

### Step 3: Import the component modules
You're done! Angular Material is now configured to be used in your application.

Import the NgModule for each component you want to use:

```ts
import {MatButtonModule} from '@angular/material/button';
import {MatCheckboxModule} from '@angular/material/checkbox';
### Step 2: Display an example Angular Material component

@NgModule({
...
imports: [MatButtonModule, MatCheckboxModule],
...
})
export class PizzaPartyAppModule { }
```
Let's display a slider component in your app and verify that everything works.

Alternatively, you can create a separate NgModule that imports and then re-exports all of the Angular Material components that you will use in your application. By exporting them again, other modules can simply include your `CustomMaterialModule` wherever Material components are needed, and automatically get all of the exported Material modules. A good place for importing/exporting the application-wide Material modules is the [SharedModule](https://angular.io/guide/ngmodule-faq#sharedmodule).
You need to import the `MatSliderModule` that you want to display by adding the following lines to your app.module.ts file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that it may be a better getting started experience for new users if they generated a nav via the nav schematic (ng g @angular/material:nav nav).

They would only need one additional step to replace their app.component.html with the <app-nav></app-nav> component after they created it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I discussed this with Jeremy and we decided to go with the MatSlider as the nav looks a bit out of place on the demo page. I'm back in the office and will address the other comments and submit my changes.


```ts
import {MatButtonModule} from '@angular/material/button';
import {MatCheckboxModule} from '@angular/material/checkbox';

@NgModule({
imports: [MatButtonModule, MatCheckboxModule],
exports: [MatButtonModule, MatCheckboxModule],
import { MatSliderModule } from '@angular/material';
…
@NgModule ({....
imports: [...,
MatSliderModule,
…]
})
export class MyOwnCustomMaterialModule { }
```

Whichever approach you use, be sure to import the Angular Material modules _after_ Angular's
`BrowserModule`, as the import order matters for NgModules.

### Step 4: Include a theme

Including a theme is **required** to apply all of the core and theme styles to your application.
Add the `<mat-slider>` tag to the `app.component.html` like so:

To get started with a prebuilt theme, include one of Angular Material's prebuilt themes globally
in your application. If you're using the Angular CLI, you can add this to your `styles.css`:
```css
@import "~@angular/material/prebuilt-themes/indigo-pink.css";
```html
<mat-slider min="1" max="100" step="1" value="1"></mat-slider>
```

If you are not using the Angular CLI, you can include a prebuilt theme via a `<link>` element in
your `index.html`.

For more information on theming and instructions on how to create a custom theme, see the
[theming guide](./theming.md).

### Step 5: Gesture Support

Some components (`mat-slide-toggle`, `mat-slider`, `matTooltip`) rely on
[HammerJS](http://hammerjs.github.io/) for gestures. In order to get the full feature-set of these
components, HammerJS must be loaded into the application.

You can add HammerJS to your application via [npm](https://www.npmjs.com/package/hammerjs), a CDN
(such as the [Google CDN](https://developers.google.com/speed/libraries/#hammerjs)), or served
directly from your app.

To install via npm, use the following command:
Run your local dev server:

#### NPM
```bash
npm install --save hammerjs
ng serve
```

#### Yarn
```bash
yarn add hammerjs
```
and point your browser to [http://localhost:4200](http://localhost:4200)

After installing, import it on your app's entry point (e.g. `src/main.ts`).
```ts
import 'hammerjs';
```
You should see the material slider component on the page.

### Step 6 (Optional): Add Material Icons
In addition to the install schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.

If you want to use the `mat-icon` component with the official
[Material Design Icons](https://material.io/icons/), load the icon font in your `index.html`.

```html
<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
```

For more information on using Material Icons, check out the
[Material Icons Guide](https://google.github.io/material-design-icons/).

Note that `mat-icon` supports any font or svg icons; using Material Icons is one of many options.


### Appendix: Configuring SystemJS
### Appendix: Installing [HammerJS](http://hammerjs.github.io/)

If your project is using SystemJS for module loading, you will need to add `@angular/material` and
`@angular/cdk` to the SystemJS configuration.
HammerJS can be installed using the following npm command:

The `@angular/cdk` package is organized of multiple entry-points.
Each of these entry-points must be registered individually with SystemJS.

Here is a example configuration where `@angular/material`, `@angular/cdk/platform` and
`@angular/cdk/a11y` are used:


```js
System.config({
// Existing configuration options
map: {
// ...
'@angular/material': 'npm:@angular/material/bundles/material.umd.js',

// CDK individual packages
'@angular/cdk/platform': 'npm:@angular/cdk/bundles/cdk-platform.umd.js',
'@angular/cdk/a11y': 'npm:@angular/cdk/bundles/cdk-a11y.umd.js',
// ...
'hammerjs': 'npm:hammerjs',
},
packages: {
//...
hammerjs: {main: './hammer.min.js', defaultExtension: 'js'}
//...
}
});
```
```bash
npm install --save hammerjs
```

After installing, import it on your app's entry point (e.g. `src/main.ts`).

### Example Angular Material projects
- [material.angular.io](https://material.angular.io) -
We build our own documentation with Angular Material!
```ts
import 'hammer.js';
```