angular-material-20

Angular Material 20 Best Practices

This project adheres to modern Angular Material best practices, emphasizing maintainability, performance, accessibility, scalability and correct usage of APIs.

Core Principles

SCSS vs CSS

• Prefer SCSS for styling, especially when theme customization is required. Angular Material has APIs written in SCSS.
• Use CSS only when you need to use theme styles generated by mat.theme mixin. Modifications or customizations for Angular Material theming are not possible with CSS.

Component & Directive Imports

Always import components and directives from @angular/material package. Avoid importing modules.

Good:

import { MatButton } from '@angular/material/button';
import { MatIcon } from '@angular/material/icon';
import { MatCard, MatCardContent } from '@angular/material/card';

Bad:

import { MatButtonModule } from '@angular/material/button';
import { MatIconModule } from '@angular/material/icon';
import { MatCardModule } from '@angular/material/card';

Theming Configuration

Always use mat.theme mixin to configure the theme. Avoid using mat.define-theme, mat.define-light-theme, mat.define-dark-theme functions and mat.core mixin.

Basic Theme Configuration

The mat.theme mixin takes a map with the following properties:

• color: Single color palette or a map of color palettes
• typography: Single typography or a map of typography properties
• density: Integer from 0 to -5 (0 = default spacing, -5 = most dense)

Simple Theme Example

@use '@angular/material' as mat;

html {
  color-scheme: light dark;
  @include mat.theme(
    (
      color: mat.$violet-palette,
      typography: Roboto,
      density: 0,
    )
  );
}

Advanced Theme with Multiple Color Palettes

@use '@angular/material' as mat;

html {
  color-scheme: light dark;
  @include mat.theme(
    (
      color: (
        primary: mat.$violet-palette,
        tertiary: mat.$orange-palette,
      ),
      typography: (
        plain-family: Roboto,
        brand-family: Open Sans,
        bold-weight: 900,
        medium-weight: 500,
        regular-weight: 300,
      ),
      density: 0,
    )
  );
}