skip to content

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