skip to content

Theme Setup & Palettes

One mat.theme mixin turns a palette, a font and a density step into the CSS variables every component reads, and color-scheme flips light and dark. Interviewers ask how a custom theme is built.

part ofAngular Material & CDKread it →
on this pageshow

explore

questions

5

In Angular Material 22, what does `ng add @angular/material` set up for theming, and how does a prebuilt theme CSS file differ?

level: juniorimportance: must knowfreq 55%

answer

  1. one command, several file edits
  2. a Sass block at the top of styles
  3. font links in index.html
  4. the body starts in light mode
  5. prebuilt CSS: compiled, one fixed mode

basics

~20 s

In Angular Material 22, ng add writes a mat.theme Sass block from the palette pair you choose, links the Roboto and Material Symbols fonts in index.html and starts the app in light mode. A prebuilt theme is a fixed, precompiled CSS file.

solid answer

~40 s

In v22 the `ng add @angular/material` schematic always writes a custom Material 3 theme. It asks for one of four palette pairs (`azure-blue` by default, `rose-red`, `magenta-violet`, `cyan-orange`) and inserts an `html { @include mat.theme(...) }` block at the top of `styles.scss`; when the project has no SCSS stylesheet it creates `material-theme.scss` and adds it to the build `styles`. The same block gives `body` `color-scheme: light`, the surface background and the body font, and the schematic links Roboto and Material Symbols Outlined in `index.html`. A prebuilt theme is one of eight compiled files in `@angular/material/prebuilt-themes/` that you list in `angular.json` `styles`: four M3 and four older M2. It needs no Sass, but its palettes and its light or dark mode are fixed.

code

scss · 22 lines
scss
@use '@angular/material' as mat;

html {
  height: 100%;
  @include mat.theme((
    color: (
      primary: mat.$azure-palette,
      tertiary: mat.$blue-palette,
    ),
    typography: Roboto,
    density: 0,
  ));
}

body {
  color-scheme: light;
  background-color: var(--mat-sys-surface);
  color: var(--mat-sys-on-surface);
  font: var(--mat-sys-body-medium);
  margin: 0;
  height: 100%;
}

go deeper

for a junior

Recall the edits: a mat.theme block in styles.scss, Roboto and Material Symbols links, and a light body. Know that a prebuilt theme is one fixed CSS file you list in angular.json.

for a middle

Explain why the generated block is a color map with primary and tertiary, and why a prebuilt M3 file cannot switch modes: it was compiled with one theme-type.

for a senior

Show you can audit a project after setup: no duplicate prebuilt file fighting the Sass theme, the body color-scheme set deliberately, and a known answer for custom builders and libraries.

for a principal

Frame the choice for several apps: a prebuilt file is zero-effort but frozen, while a generated Sass theme is a small file each team owns and can extend with brand palettes.

## What the schematic changes `ng add @angular/material` installs the package and then runs Angular Material's own setup schematic. For an **application** project in v22.2.1 that schematic makes these edits: 1. **Dependencies** - it makes sure `@angular/cdk` (at the same version as Material) and `@angular/forms` are in `package.json`. 2. **A theme** - it asks you to *"Select a pair of starter prebuilt color palettes"*. The four choices are `azure-blue` (the default), `rose-red`, `magenta-violet` and `cyan-orange`. Whatever you pick, it writes **Sass**, not a link to a CSS file: a `mat.theme` block is inserted at the top of the project's `styles.scss`. 3. **A fallback file** - if the project has no SCSS global stylesheet (for example it uses `styles.css`), it creates `material-theme.scss` in the source root and adds it to the `build` target's `styles` array instead. 4. **Fonts** - it adds preconnect links plus stylesheet links for the **Roboto** font and the **Material Symbols Outlined** icon font to `index.html`. For a **library** project it only logs that no further setup is needed: libraries do not ship a global theme. ## The theme block it writes The generated block (abridged) looks like this for `azure-blue`: ```scss @use '@angular/material' as mat; html { @include mat.theme(( color: (primary: mat.$azure-palette, tertiary: mat.$blue-palette), typography: Roboto, density: 0, )); } body { color-scheme: light; background-color: var(--mat-sys-surface); color: var(--mat-sys-on-surface); font: var(--mat-sys-body-medium); } ``` Three things to notice: - The palette pair becomes a **color map** with `primary` and `tertiary`, so you can later swap either palette or add your own generated one. - `mat.theme` emits **CSS variables**; the `body` rule uses them so the page background and text match the components. - `color-scheme: light` on `body` means the app is **light by default**, even on a dark operating system, until you change that value. The comment in the generated file says so. ## The eight prebuilt theme files A **prebuilt theme** is a CSS file that Angular Material already compiled from the same Sass API with fixed inputs. You add one to the `styles` array of `angular.json`: ```json "styles": ["@angular/material/prebuilt-themes/azure-blue.css"] ``` | File | Design system | Mode | Palettes (primary, tertiary) | |---|---|---|---| | `azure-blue.css` | M3 | light | azure, blue | | `rose-red.css` | M3 | light | rose, red | | `cyan-orange.css` | M3 | dark | cyan, orange | | `magenta-violet.css` | M3 | dark | magenta, violet | | `deeppurple-amber.css` | M2 | light | deep purple, amber | | `indigo-pink.css` | M2 | light | indigo, pink | | `pink-bluegrey.css` | M2 | dark | pink, blue grey | | `purple-green.css` | M2 | dark | purple, green | The M3 files are compiled with an explicit `theme-type` of `light` or `dark`, so each one contains **only one set of colour values**. Changing `color-scheme` does not turn `azure-blue.css` dark. The M2 files exist for backwards compatibility, and the theming guide says they will be removed in a future version. ## Choosing between them - Use the **generated Sass theme** whenever the app has a brand colour, a brand font, a density preference or needs to follow light and dark mode. It is what `ng add` gives you anyway. - Use a **prebuilt file** for a prototype, a demo, or a build pipeline without Sass, accepting one palette pair and one mode. - Do not load a prebuilt file *and* a `mat.theme` block for the same scope: both declare the same variables, and whichever rule wins the cascade silently decides the colours. ## Common surprises after setup - **"Dark mode does nothing."** The generated `body { color-scheme: light; }` pins the light values. Change it to `light dark` to follow the operating system, or to `dark`. - **Bold text looks synthetic.** The generated font link loads Roboto weights 300, 400 and 500, while `typography: Roboto` uses 700 for bold, so add the 700 weight to the link if bold text matters. - **Running it twice.** When the schematic has to create `material-theme.scss` and that file already exists, it warns and skips theme generation. With a `styles.scss` it inserts the block again, so check for a duplicate. - **Custom builders.** When the schematic must add `material-theme.scss` to the build `styles` but the `build` target does not use the Angular CLI's default builder, it stops with an error.

  • The journey-planner team picked azure-blue in ng add. Is the azure-blue.css prebuilt file now in angular.json?
    No. In v22 the schematic turns the chosen pair into a `mat.theme` Sass block with `primary: mat.$azure-palette` and `tertiary: mat.$blue-palette`. Nothing is added to `styles` unless the project has no SCSS stylesheet, and then the added entry is the generated `material-theme.scss`, not a prebuilt CSS file.
  • Why can't you make cyan-orange.css follow a light operating-system setting?
    It was compiled with `theme-type: dark`, so it contains only dark colour values rather than `light-dark()` pairs. `color-scheme` has nothing to switch between. To get both modes you write your own `mat.theme` call, whose default emits both sets.
  • What does ng add do when you run it in a library project of the workspace?
    It installs the packages but adds no theme and no font links; it logs that a library needs no further setup. The application that consumes the library owns the global theme.

  • ng add adds the chosen prebuilt CSS file to angular.json
  • A prebuilt M3 file switches to dark when color-scheme is dark
  • ng add imports a theming module into the root component
  • The app follows the OS dark setting right after ng add
  • The M2 prebuilt files are the recommended choice for new apps

Assumes Angular Material 22.2.1; ng add has always written a custom mat.theme Sass block since 20.1.1 (v19 moved its custom theme to mat.theme; earlier releases could add a prebuilt CSS file instead).

open as a page

In Angular Material 22, how do you build a custom `mat.theme` from a brand colour, a brand font and a density step?

level: middleimportance: must knowfreq 52%

basics

~20 s

Generate palettes from the brand hex with ng generate @angular/material:theme-color, then pass them, a font and a density step from 0 to -5 to mat.theme under html. It emits the CSS variables every component reads.

open as a page

In Angular Material 22, how do `color-scheme` and the CSS `light-dark()` function switch a `mat.theme` between light and dark?

level: middleimportance: should knowfreq 45%

basics

~20 s

By default mat.theme writes each colour variable as a light-dark(light, dark) pair, and the browser picks one from the color-scheme in effect. Declare color-scheme: light dark to follow the operating system, or light or dark on a toggled class.

open as a page

When moving an Angular Material app from an M2 theme built with `mat.m2-define-light-theme` to Material 3 in v22, what must change?

level: seniorimportance: should knowfreq 30%

basics

~20 s

No automated migration exists: replace the m2-define-* config and component theme mixins with one mat.theme under html, then handle what M3 drops, chiefly the color input's primary, accent and warn variants, M2 typography class names and custom mixins reading the M2 config.

open as a page

In Angular Material 22, how do you give one region, such as a dense control-room console, its own density or palette, and what does it cost?

level: seniorimportance: should knowfreq 32%

basics

~20 s

Include mat.theme again under the region's selector, passing only what changes, such as density: -2; the redeclared CSS variables inherit to the components inside. Each call re-emits that category's variable set, and a dialog attached outside the region misses it.

open as a page