skip to content

Style Overrides & Tokens

Restyling a Material component goes through its overrides mixin or the --mat-sys system variables, never its private classes. Interviewers ask why ::ng-deep hacks break on the next upgrade.

part ofAngular Material & CDKread it →
on this pageshow

explore

questions

5

In Angular Material 22, how do you restyle one component type, such as `mat-card`, with its overrides mixin, and how is that change scoped?

level: middleimportance: must knowfreq 45%

answer

  1. one Sass mixin per component
  2. token keys without the component prefix
  3. Styling tab lists the keys
  4. selector decides who inherits it
  5. a typo fails the build

basics

~20 s

Include the component's overrides mixin, such as mat.card-overrides, with a map of its token names and values. It sets the card's CSS variables under the selector you include it in: html reaches every card, a class only the cards inside it.

solid answer

~40 s

Each component exposes a Sass mixin named `mat.<component>-overrides`: `mat.card-overrides`, `mat.button-overrides`, `mat.form-field-overrides` and so on. You pass a map of that component's tokens, written without the component prefix, for example `elevated-container-color`, `elevated-container-shape` and `title-text-size` for the card. The mixin writes variables such as `--mat-card-elevated-container-color` under the current selector, or under `html` when it is called at the top level, and the card's styles read those variables before falling back to the system values. Scope is therefore ordinary CSS inheritance: include it under `html` for every card, under `.course-summary` for cards inside that container. The mixin checks every key against the component's token list and fails the Sass build with an invalid-token-name error on a typo; the keys are listed on each component's Styling tab in the documentation.

code

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

// Every card in the app
html {
  @include mat.card-overrides((
    elevated-container-shape: 4px,
  ));
}

// Only cards inside the course summary
.course-summary {
  @include mat.card-overrides((
    elevated-container-color: var(--mat-sys-surface-container-high),
    title-text-size: 1.25rem,
  ));
}

go deeper

for a junior

Recall that each Material component has a mat.<component>-overrides Sass mixin taking a map of its token names and values.

for a middle

Explain prefix-free keys, where the key list is documented, how the selector you include the mixin under sets its scope, and how the component falls back to system variables.

for a senior

Show how validation turns a renamed token into a build error, how variant groups map to appearances, and how app-wide and page-level overrides compose.

for a principal

Decide which brand rules belong in component overrides and which in system values, so the theme file stays short and upgrades stay mechanical.

## What a component overrides mixin is Angular Material 22 styles each component from **tokens**: named design decisions such as a card's container color, its corner shape or its title font size. Each component publishes a Sass mixin, `mat.<component>-overrides`, that lets you set any of its tokens without touching the component's DOM or CSS classes. Examples include `mat.card-overrides`, `mat.button-overrides`, `mat.form-field-overrides`, `mat.select-overrides`, `mat.table-overrides` and `mat.tabs-overrides`. The mixin takes one argument, a Sass map from token name to value: ```scss @use '@angular/material' as mat; .course-summary { @include mat.card-overrides(( elevated-container-color: var(--mat-sys-surface-container-high), elevated-container-shape: 4px, title-text-size: 1.25rem, )); } ``` ## Finding the token names The keys are the component's tokens with the component prefix removed: inside the source the card token is `card-elevated-container-color`, and in the overrides map you write `elevated-container-color`. Two places list them: - the **Styling** tab of each component's documentation page, generated from the token definitions; - the component's `_m3-<name>.scss` file in the source, such as `_m3-card.scss`. | Component | Mixin | Example keys | |---|---|---| | Card | `mat.card-overrides` | `elevated-container-color`, `elevated-container-shape`, `outlined-outline-color`, `title-text-size` | | Button | `mat.button-overrides` | `filled-container-color`, `filled-label-text-color`, `filled-container-shape`, `outlined-outline-color` | | Form field | `mat.form-field-overrides` | `outlined-outline-color`, `outlined-focus-outline-color`, `outlined-container-shape` | Tokens are grouped by **variant**. A card's default appearance is `raised`, which the `elevated-*` tokens style; `outlined-*` and `filled-*` style the other two appearances. A button's `filled-*` tokens style `matButton="filled"`, not the text or outlined buttons. ## How the value reaches the component The mixin emits plain CSS custom properties. For the card above the output is roughly `--mat-card-elevated-container-color: ...` declared on `.course-summary`. The card's own stylesheet reads its background as a variable with a fallback: 1. first `--mat-card-elevated-container-color`, the component token; 2. if that is not set, `--mat-sys-surface-container-low`, the system variable from the theme. So an override wins wherever it is inherited, and a card outside that scope still gets the theme's value. ## A worked example A university course-registration portal has a brand book that asks for three things on its course pages: squarer cards, a darker outline on outlined form fields, and a title size that matches its print material. Each rule maps to one mixin and one or two keys: | Brand-book rule | Mixin | Key | |---|---|---| | Cards with 4px corners | `mat.card-overrides` | `elevated-container-shape` | | Darker outline on outlined fields | `mat.form-field-overrides` | `outlined-outline-color`, `outlined-hover-outline-color` | | Card titles at 1.25rem | `mat.card-overrides` | `title-text-size` | Writing the brand book down as this table first is useful in review: every row names a documented token, so nothing in the stylesheet depends on how the components are built inside. ## Scoping Because the result is inherited custom properties, scope is decided by **where you include the mixin**: - under `html`, or at the top level of the theme file, which the mixin wraps in `html` for you: every card in the app; - under a class such as `.course-summary`: only cards inside elements with that class; - under a component's host selector in a global stylesheet: only cards inside that component. Overrides compose. The app can set a radius for all cards at `html`, and the summary page can override only the color for its own subtree; the radius still comes from the outer declaration. ## Validation and why it matters on upgrade `mat.<component>-overrides` checks each key against that component's token list. An unknown key, such as `card-elevated-container-shape` with the prefix left on, or a token the component never had, fails the Sass build with an error that names the invalid token and lists the valid ones. The theming guide presents this as the reason to prefer the mixin over declaring `--mat-card-*` variables by hand: if a token is renamed, moved or removed in a later release, your build tells you, instead of the style quietly no longer applying. ## Common mistakes - Writing the prefixed name (`card-title-text-size`) as the key. - Setting `filled-*` button tokens and wondering why the outlined buttons did not change. - Expecting an include in one page's stylesheet to restyle cards on other pages; the variables only reach elements under the selector they are declared on. - Using a component mixin for a change that belongs to the whole theme, such as the brand's primary color, which then has to be repeated for every component.

  • Why does `mat.button-overrides((filled-container-color: ...))` leave some buttons unchanged?
    Button tokens are grouped by appearance. `filled-*` tokens style buttons with the filled appearance (`matButton="filled"`); text, elevated, outlined and tonal buttons read their own token groups. Set the matching group, such as `outlined-outline-color`, for each appearance the brand book covers.
  • What happens when a card sits inside two elements that both include `mat.card-overrides` with the same key?
    The values are inherited custom properties, so the nearest ancestor declaration wins, exactly like any inherited CSS variable. Keys set only on the outer element still reach the card, which lets an app-wide default and a page-level tweak combine.
  • Can an overrides value refer to a system variable?
    Yes. The value is emitted as written, so `elevated-container-color: var(--mat-sys-surface-container-high)` keeps the card tied to the theme, including its light and dark values, while still differing from the default role.

  • Writes token keys with the component prefix, such as card-title-text-size.
  • Thinks the mixin restyles every component, not only the named one.
  • Believes a misspelled key is silently ignored by the component mixin.
  • Assumes filled-* button tokens also restyle outlined and text buttons.
  • Finds token names by reading internal class names in DevTools.
open as a page

A university course-registration portal restyled Angular Material buttons with `::ng-deep .mdc-button--unelevated` rules, and the brand color vanished after an upgrade; why, and what is the supported fix?

level: seniorimportance: must knowfreq 41%

basics

~20 s

Angular Material treats each component's DOM structure and CSS classes as private details that can change in any release, so selectors aimed at them break without warning. The supported fix is the overrides mixins, such as mat.button-overrides, or the --mat-sys variables.

open as a page

In Angular Material 22, what are the `--mat-sys-*` CSS variables, and how do you use them to style your own components?

level: juniorimportance: should knowfreq 38%

basics

~20 s

They are CSS custom properties that Angular Material's mat.theme mixin declares for the theme's color roles, type scale, shapes and elevation. Your own styles read them, such as background: var(--mat-sys-surface), and follow the theme, light and dark values included.

open as a page

What does Angular Material 22's `mat.strong-focus-indicators()` mixin change about keyboard focus, and how do you adjust its outline?

level: seniorimportance: should knowfreq 24%

basics

~20 s

Most Angular Material components show focus only as a faint background tint by default. mat.strong-focus-indicators() turns on a visible keyboard-focus outline, 3px solid in the theme's secondary color by default; a config map and strong-focus-indicators-theme adjust it.

open as a page

In Angular Material 22, when do you change a system token with `mat.theme-overrides` instead of a component's overrides mixin, and what does each one reach?

level: seniorimportance: should knowfreq 31%

basics

~20 s

mat.theme-overrides, or mat.theme's $overrides map, rewrites a --mat-sys system variable, so every component and custom style reading it changes under that selector. A component overrides mixin sets only that component's tokens, which win over the system fallback.

open as a page