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?
answer
- one Sass mixin per component
- token keys without the component prefix
- Styling tab lists the keys
- selector decides who inherits it
- a typo fails the build
basics
~20 sInclude 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 sEach 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@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
Recall that each Material component has a mat.<component>-overrides Sass mixin taking a map of its token names and values.
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.
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.
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.