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 version && npm -v && node -v to check your versions. This guide was written using Angular CLI 11.0.4, Npm 6.14.8, and Node 14.15.0.

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
cd 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 config schematics.@schematics/angular:component.styleext scss

Changing the default stylesheet processor will not affect your existing styles. However, you do not have to make Sass the default stylesheet processor to use Sass. Even when using another default, the Angular CLI will process Sass stylesheets just fine, provided they have the correct extension (scss).

Alternatively, you can use any other stylesheet processor and customize the appearance of your website with CSS variables, instead of through Sass. Using CSS variables has some limitations in what you can customize, and though supported by most browsers, there are some exceptions, such as Internet Explorer. See Can I Use CSS Variables.

Step 2: Install Blox Material

Now add the Blox Material library to your project:

npm install --save @blox/material

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 in your application ends up in the bundles that are loaded by the browser.

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

Add the following code to your src/styles.scss file:

// customize some theme variables, when importing @material/theme:
@use "@material/theme" with (
  $primary: #ba6b6c,
  $secondary: #459493,
  $background: #f5f5f5,
  $surface: #f5f5f5,
  $on-primary: #fff,
  $on-secondary: #000,
  $on-surface: #000
);
// import styles for all mdc components:
@use "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:

@use "@material/theme" with ($primary: #ba6b6c);
@use "@material/button/mdc-button";
@use "@material/card/mdc-fab";

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 pages.

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">

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 ng serve 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.