Getting Started

This guide gets you started with Blox Material in new or existing projects created with the Angular CLI. The Angular CLI only works with Node installed. So if you don't already have a recent Node version running, please refer to Node Downloads for instructions to install Node and Npm on your computer. To install (or upgrade to) the latest Angular CLI, run:

npm install -g @angular/cli

Check that you are using recent versions of Angular CLI, Node, and Npm: run ng -v && npm -v && node -v to check your versions. This guide was written using Angular CLI 6.0.3, Npm 6.0.0, and Node 8.11.1.

Step 1: Prepare your Angular Project

Although not required, using Sass is highly recommended with Blox Material projects. The Material styling/themes are much easier to customize with Sass. For new projects, use Angular CLI to bootstrap the project, and make scss (Sass) the default stylesheet preprocessor:

ng new NAME-OF-PROJECT --style=scss\ncd NAME-OF-PROJECT

For existing projects that do not use Sass yet, you can switch to Sass as default stylesheet preprocessor with the following command (run inside the root directory of your project):

ng set defaults.styleExt scss

Then simply rename src/styles.css to src/styles.scss, and in the configuration file angular.json also change the reference to styles.css to refer to styles.scss instead. (You can find that under projects/NAME-OF-PROJECT/architect/build/options/styles in the file). Since scss is an extension of css, this will not affect your existing styles.

For existing projects, also make sure that you are using at least Angular CLI 6.0.0 (Angular CLI uses the version installed for your project, not the globally installed version). This can be checked by running ng -v in the project directory. If the project uses an older Angular CLI version, upgrade it by running npm install --save-dev @angular/cli in your project directory.

Step 2: Install Blox Material

Now add the Blox Material library to your project:

npm install --save @blox/material

Next install @angular/forms (optional):

npm install --save @angular/forms

And add the Material module to your application (in src/app/app.module.ts):

import { FormsModule } from '@angular/forms'; // (optional)
import { MaterialModule } from '@blox/material';

@NgModule({
    ...
    imports: [
        BrowserModule,
        FormsModule,      // using FormsModule is optional
        MaterialModule,
        ...
    ],
    ...
})
export class MyAppModule { }

Blox Material is designed in such a way that only components, directives, and services that are used in your application end up in the final production build. (The code is effectively tree-shakeable by the Angular CLI, and other build tools like Webpack and Rollup). Thus there is no need for smaller partial modules for separate components, like other Angular frameworks typically offer. Just import the complete MaterialModule, only functionality that is actually used is going to your customers!

The example also includes the @angular/forms FormsModule. Using the FormsModule is not a requirement of Blox Material. All Blox Material components can also be used without the FormsModule. However, the FormsModule makes building forms a brease, with easy binding of controls to data, addition of validation rules, display of errors, and much more. Please refer to Angular Forms Guide for more in depth information.

Blox Material is fully compatible with @angular/forms, and supports both the FormsModule, and the ReactiveFormsModule. But all Blox Material features can also be used without the @angular/forms package.

Step 3: Import and Customize a Theme

To tell the Sass preprocessor how to find all Material Components theme files, add the following configuration to the build options section of your project in the angular.json file (under projects/NAME-OF-PROJECT/architect/build/options:

{
    "projects": { "NAME-OF-PROJECT": { "architect": { "build": {
        ...
        "options": {
            ...
            "styles": ...
            ...
            "stylePreprocessorOptions": {
                "includePaths": [
                    "node_modules"
                ]
            },
            ...
        }
    }}}}
    ...
}

Next, add the following code to your src/styles.scss file:

// customize some theme variables, e.g.:
$mdc-theme-primary: #6200ee;
$mdc-theme-secondary: #018786;
$mdc-theme-background: #fff;

// import theming for all mdc components:
@import "material-components-web/material-components-web";

This will add theme styles for all available Material components. If you only use a couple of components, you can save memory by only including the theme files for the components you actually use. For example:

@import "@material/button/mdc-button";
@import "@material/card/mdc-fab";

To use Google's Material Icons, and the Roboto font (default font for the Material Components), you may also want to add the following stylesheets to the head section of the src/index.html file (both are optional):

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

For more information about customizing and extending the theme, see Material Components Web Theme Documentation. Most components also define Sass variables and/or mixins to further customize their appearance. Links to the documentation for these Sass rules can be found on the component's documentation page.

Step 4: Use Material Components!

Open src/app/app.component.html and add some markup, for example:

<button mdcButton raised>My First Material Button</button>

Next, run npm run start and when the application starts, navigate to http://localhost:4200. Validate you see the added button, and that it is correctly styled. Congratulations! You have made your first Angular App with Blox Material! The Components section of this website contains documentation and code samples for all supported Material components. You can even experiment with the demos by editing the source code without leaving your browser!

If you have to support Internet Explorer, a few extra steps are required. Luckily we wrote a guide to help you with that as well: Building for Internet Explorer 11.