angular-material

name

angular-material

description

Guides Angular Material v3 (M3) theming — the mat.theme() mixin, system-level --mat-sys-* CSS tokens, color/typography/density configuration, and system/component token overrides. Angular Material v3's theme API is a near-total rewrite of v2's (M2's define-light-theme/define-dark-theme + all-component-themes pattern), so trigger this skill whenever the user is setting up a new Material theme, styling a custom component to match the Material theme, switching between light/dark mode, generating a custom color palette, adjusting density, or migrating an existing Material app from v2/M2 theming to v3/M3 theming — even if they just say "add Material theming", "make my component look like Material", or "fix my Material colors" without naming M3 explicitly.

Angular Material v3 Theming

Angular Material v3 (M3 — the default palette system since Angular Material v17, with a rewritten single-mixin Sass API since v19) replaced the old primary/accent/warn theme-building pattern with one mat.theme() mixin and a set of --mat-sys-* CSS custom properties that both Material components and your own components can read. Don't reach for mat.define-light-theme, mat.define-dark-theme, mat.all-component-themes, or color="accent" — those are the v2 (M2) API and are either gone or deprecated compatibility shims in v3.

Before you start

Check the installed @angular/material version (package.json or npm ls @angular/material) — the theming API changed twice, so which one applies depends on the version:

• v19+: use mat.theme() — the current API, described below.
• v17–v18: M3 is the default palette system, but the single-mixin mat.theme() API doesn't exist yet. Use mat.define-theme() plus the older component mixins — see references/migration-from-v2.md.
• v16 or older: the app is still on M2 (primary/accent/warn palettes, mat.define-light-theme, mat.all-component-themes). Point the user at references/migration-from-v2.md to move it to M3.

Quick start

@use '@angular/material' as mat;

html {
  color-scheme: light dark; // lets mat.theme() pick light/dark via the CSS light-dark() function
  @include mat.theme((
    color: mat.$violet-palette,
    typography: Roboto,
    density: 0,
  ));
}

One @include mat.theme(...) on html replaces the entire old pattern of building primary/accent/warn palettes by hand, wrapping them in define-light-theme/define-dark-theme, and calling all-component-themes. It emits both the Sass-driven component styles and the --mat-sys-* CSS custom properties in one pass.

ng add @angular/material scaffolds a file like this for a new project. ng generate @angular/material:theme-color generates a custom color palette from a source color instead of using a prebuilt one.

Reference files

• theme-api.md — the full mat.theme() config map (color, typography, density), overriding system and per-component tokens, the --mat-sys-* CSS variables, mat.system-classes() utility classes, and mat.strong-focus-indicators(). Read this for anything about configuring or customizing a v3 theme.
• migration-from-v2.md — what changed from M2 to M3 (terminology, API shape, the new per-include selector-wrapping requirement), the color-variants-backwards-compatibility mixin, get-theme-version, and the pre-v19 mat.define-theme() API. Read this when touching an app that still has M2 (or early M3) theming.

Styling your own components

Don't hardcode colors or font sizes in custom components that live inside a Material-themed app — read the theme through the --mat-sys-* CSS variables instead (e.g. color: var(--mat-sys-on-surface)), or use the mat.system-classes() utility classes. Both stay in sync automatically when the user switches light/dark mode or changes the palette, which hand-picked colors never do. Details and common token names are in theme-api.md.