Theming - Angular Components

Overview

Angular Material’s theming system lets you customize the appearance of your components by defining color palettes, typography, and density. The theming system is based on Google’s Material Design specification and uses Material Design tokens.

This guide describes the theming system introduced in Angular Material v19. If you’re using an earlier version, refer to v18.material.angular.dev/guides.

Getting Started

Your application needs a theme file that includes Angular Material’s mat.theme mixin. This mixin generates CSS variables based on your color, typography, and density settings.

Basic Theme

Create a theme file (e.g., theme.scss) that applies a color palette, typography, and density:

theme.scss

@use '@angular/material' as mat;

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

This theme:

Uses the violet color palette
Applies Roboto font family
Uses standard density (0)
Supports both light and dark modes via color-scheme: light dark

Applying Background Colors

To apply the theme’s surface colors to your application:

styles.scss

body {
  background: var(--mat-sys-surface);
  color: var(--mat-sys-on-surface);
}

Or use utility classes:

theme.scss

html {
  @include mat.theme((/* ... */));
  @include mat.system-classes();
}

<body class="mat-bg-surface mat-text-on-surface">

Color Palettes

The theme’s color determines component styles like button fills, checkbox colors, and ripple effects.

Single Color Palette

Provide a single palette to use for primary, secondary, and tertiary colors:

@use '@angular/material' as mat;

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

Prebuilt Color Palettes

Angular Material provides twelve prebuilt palettes:

Red

mat.$red-palette

Green

mat.$green-palette

Blue

mat.$blue-palette

Yellow

mat.$yellow-palette

Cyan

mat.$cyan-palette

Magenta

mat.$magenta-palette

Orange

mat.$orange-palette

Chartreuse

mat.$chartreuse-palette

Spring Green

mat.$spring-green-palette

Azure

mat.$azure-palette

Violet

mat.$violet-palette

Rose

mat.$rose-palette

Color Map with Multiple Palettes

Customize primary, secondary, and tertiary colors separately:

@use '@angular/material' as mat;

html {
  @include mat.theme((
    color: (
      primary: mat.$violet-palette,
      tertiary: mat.$orange-palette,
      theme-type: light,
    ),
    typography: Roboto,
    density: 0
  ));
}

Theme Type Options

The theme-type determines how colors are defined:

color-scheme (Default)
light
dark

Includes both light and dark colors using the CSS light-dark() function:

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

The application follows user’s system preferences.

Only defines light color values:

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

Only defines dark color values:

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

Custom Color Palettes

Generate custom palettes using the Angular CLI schematic:

ng generate @angular/material:theme-color

This schematic creates a custom palette file based on your color inputs for primary, secondary, tertiary, and neutral colors.

Typography

The typography configuration controls text styles across all components.

Single Font Family

Apply one font family to all text:

@use '@angular/material' as mat;

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

This uses:

700 for bold text
500 for medium text
400 for regular text

Typography Map

Customize font families and weights:

@use '@angular/material' as mat;

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

plain-family: Used for body text
brand-family: Used for headings and titles
bold-weight, medium-weight, regular-weight: Font weight values

Loading Fonts

Load fonts from Google Fonts in your index.html:

index.html

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@300;500;900&family=Roboto:wght@400;500;700&display=swap" rel="stylesheet">

Angular CLI projects automatically inline Google Fonts to reduce render-blocking requests.

Density

Density controls component spacing and size. Values range from 0 (default) to -5 (most dense).

@use '@angular/material' as mat;

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

Each step down reduces sizes by 4px:

Density 0

Default spacing - most comfortable for general use

Density -1

Slightly more compact - 4px smaller

Density -2

Compact - 8px smaller

Density -3

Very compact - 12px smaller

Density -4

Extremely compact - 16px smaller

Density -5

Maximum density - 20px smaller

Setting density below 0 can reduce accessibility. High density may make navigation harder for users of assistive technology.

Light and Dark Mode

By default, mat.theme uses the CSS light-dark() function to support both light and dark modes.

Automatic Mode Switching

Follow user’s system preferences:

@use '@angular/material' as mat;

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

Explicit Light or Dark

Force a specific mode:

html {
  color-scheme: light;
  @include mat.theme((/* ... */));
}

Class-Based Mode Toggle

Toggle mode with a CSS class:

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

body.dark-mode {
  color-scheme: dark;
}

toggleDarkMode() {
  document.body.classList.toggle('dark-mode');
}

Multiple Themes

Apply different themes in different contexts:

@use '@angular/material' as mat;

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

.warning-section {
  @include mat.theme((
    color: mat.$orange-palette,
  ));
}

Using Theme Styles

Access theme CSS variables in your custom components:

my-component.scss

.my-banner {
  background: var(--mat-sys-primary-container);
  color: var(--mat-sys-on-primary-container);
  border: 1px solid var(--mat-sys-outline-variant);
  font: var(--mat-sys-body-large);
}

Or use utility classes:

<div class="mat-bg-primary-container mat-text-on-primary-container mat-border-variant mat-font-body-lg">
  Important message
</div>

Customizing Tokens

System Tokens

Override system-level tokens:

@use '@angular/material' as mat;

html {
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0
  ));
  
  .custom-primary {
    @include mat.theme-overrides((
      primary-container: #84ffff
    ));
  }
}

Or pass overrides directly:

html {
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0
  ), $overrides: (
    primary-container: orange,
  ));
}

Component Tokens

Customize individual components:

html {
  @include mat.card-overrides((
    elevated-container-color: red,
    elevated-container-shape: 32px,
    title-text-size: 2rem,
  ));
}

See each component’s documentation for available tokens.

Strong Focus Indicators

Enable highly visible focus outlines for better accessibility:

@use '@angular/material' as mat;

html {
  @include mat.theme((/* ... */));
  @include mat.strong-focus-indicators();
}

Customize Focus Indicators

@include mat.strong-focus-indicators((
  border-color: red,
  border-style: dotted,
  border-width: 4px,
  border-radius: 2px,
));

Shadow DOM

If using Shadow DOM, load theme styles within each shadow root:

@Component({
  selector: 'app-shadow',
  template: '<button mat-raised-button>Click me</button>',
  styles: [`
    @import '@angular/material/prebuilt-themes/azure-blue.css';
  `],
  encapsulation: ViewEncapsulation.ShadowDom
})
export class ShadowComponent {}

Or use Constructable Stylesheets.

Next Steps

Typography

Learn more about typography configuration

Accessibility

Accessibility features and best practices

Component Theming

Theme your custom components

Material Design

Material Design specification

Overview

Essentials

​Overview

​Getting Started

​Basic Theme

​Applying Background Colors

​Color Palettes

​Single Color Palette

​Prebuilt Color Palettes

Red

Green

Blue

Yellow

Cyan

Magenta

Orange

Chartreuse

Spring Green

Azure

Violet

Rose

​Color Map with Multiple Palettes

​Theme Type Options

​Custom Color Palettes

​Typography

​Single Font Family

​Typography Map

​Loading Fonts

​Density

​Light and Dark Mode

​Automatic Mode Switching

​Explicit Light or Dark

​Class-Based Mode Toggle

​Multiple Themes

​Using Theme Styles

​Customizing Tokens

​System Tokens

​Component Tokens

​Strong Focus Indicators

​Customize Focus Indicators

​Shadow DOM

​Next Steps

Typography

Accessibility

Component Theming

Material Design

Build docs developers (and LLMs) love

Overview

Getting Started

Basic Theme

Applying Background Colors

Color Palettes

Single Color Palette

Prebuilt Color Palettes

Color Map with Multiple Palettes

Theme Type Options

Custom Color Palettes

Typography

Single Font Family

Typography Map

Loading Fonts

Density

Light and Dark Mode

Automatic Mode Switching

Explicit Light or Dark

Class-Based Mode Toggle

Multiple Themes

Using Theme Styles

Customizing Tokens

System Tokens

Component Tokens

Strong Focus Indicators

Customize Focus Indicators

Shadow DOM

Next Steps