Angular Material and the Angular CDK 22.3.0 were released on 18 November 2026. It is a minor release with two new Material features and a set of accessibility fixes: chips can now show a proper leading icon, and the stepper gets a styling token for the header icon shape. Neither is huge on its own, but both remove small hacks that many Angular apps carry today.
This tutorial shows how to update, how to use the new chip leading icon (and how it differs from an avatar), how to restyle stepper icons, and which fixes are worth knowing. Sources: the angular/components v22.3.0 release notes, the chips pull request #34028 and the stepper pull request #33963.
Step 1: Update
ng update @angular/[email protected] @angular/[email protected]
Or with npm directly:
npm install @angular/[email protected] @angular/[email protected]
Keep @angular/material and @angular/cdk on the same version.
Step 2: Leading icons in chips
Until now, a chip’s front slot only accepted an avatar, marked with matChipAvatar, which is meant for images such as a profile photo. People used it for icons too, but icons then picked up avatar styling, such as the round shape. The PR describes the problem plainly: “Currently users can only project an avatar in the leading slot which is used for images.”
22.3 adds a dedicated directive: matChipLeadingIcon (also usable as the <mat-chip-leading-icon> element).
Basic example
import { Component } from '@angular/core';
import { MatChipsModule } from '@angular/material/chips';
import { MatIconModule } from '@angular/material/icon';
@Component({
selector: 'app-trip-tags',
imports: [MatChipsModule, MatIconModule],
template: `
<mat-chip-set aria-label="Trip items">
<mat-chip>
<mat-icon matChipLeadingIcon>flight</mat-icon>
Flight
</mat-chip>
<mat-chip>
<mat-icon matChipLeadingIcon>hotel</mat-icon>
Hotel
<mat-icon matChipTrailingIcon>star</mat-icon>
</mat-chip>
<mat-chip>
<mat-icon matChipLeadingIcon>music_note</mat-icon>
Music
<button matChipRemove aria-label="Remove music">
<mat-icon>cancel</mat-icon>
</button>
</mat-chip>
</mat-chip-set>
`,
})
export class TripTagsComponent {}
This is the same pattern as the new official “Chips with icons” example. A chip still has two icon slots: the front slot (avatar or leading icon) and the back slot (matChipTrailingIcon or matChipRemove).
Avatar or leading icon?
| Use | Directive | Typical content |
|---|---|---|
| A picture of a person or thing | matChipAvatar |
<img> |
| A symbol that describes the chip | matChipLeadingIcon |
<mat-icon> |
A follow-up fix in the same release ensures the avatar shape is not applied to leading icons.
Accessibility note
The new directive sets aria-hidden="true" on the icon, just like the trailing icon. The icon is treated as decoration, so the chip text must carry the meaning on its own. “Flight” with a plane icon is fine. An icon-only chip is not.
Works in every chip type
The chips documentation says all variants support icons, including <mat-chip>, <mat-chip-option> and <mat-chip-row>. A filter list might look like this:
<mat-chip-listbox aria-label="Filter by status" multiple>
<mat-chip-option value="open">
<mat-icon matChipLeadingIcon>radio_button_unchecked</mat-icon>
Open
</mat-chip-option>
<mat-chip-option value="done">
<mat-icon matChipLeadingIcon>check_circle</mat-icon>
Done
</mat-chip-option>
</mat-chip-listbox>
Testing with harnesses
The chip test harness gains getLeadingIcon() and a new MatChipLeadingIconHarness:
import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
import { MatChipHarness } from '@angular/material/chips/testing';
it('shows a leading icon on each trip chip', async () => {
const loader = TestbedHarnessEnvironment.loader(fixture);
const chips = await loader.getAllHarnesses(MatChipHarness);
for (const chip of chips) {
expect(await chip.getLeadingIcon()).not.toBeNull();
}
});
One thing to check if you extend MatChip
In the public API, the leadingIcon property on MatChip is now typed as MatChipLeadingIcon, and a new avatar property holds the MatChipAvatar. Most apps never touch these, but if you have a custom chip component or a test that reads chip.leadingIcon to find an avatar, switch it to chip.avatar.
Step 3: Change the stepper icon shape
Stepper header icons (the numbered circles) were hard-coded to border-radius: 50%. In 22.3 they read a new design token instead: stepper-header-icon-shape. The default stays round, corner-full in the M3 theme and 50% in M2, so nothing changes unless you set it.
Material’s component styles read tokens as CSS custom properties with the --mat- prefix, so you can override it on a wrapper element:
/* Rounded squares instead of circles */
.onboarding-stepper {
--mat-stepper-header-icon-shape: 8px;
}
<mat-stepper class="onboarding-stepper" linear>
<mat-step label="Account">...</mat-step>
<mat-step label="Profile">...</mat-step>
<mat-step label="Done">...</mat-step>
</mat-stepper>
If you prefer Sass, use the stepper overrides mixin from your theme file; the stepper “Styling” tab in the Angular Material docs lists the exact token keys for your version. Either way, you no longer need a deep selector like ::ng-deep .mat-step-icon { border-radius: ... }.
Fixes worth knowing
The 22.3.0 and 22.3.0-rc.0 notes include several accessibility and behaviour fixes:
- Combobox (Angular Aria): relayed keyboard events are now queued, so fast back-to-back key presses are no longer dropped.
- Active item sync: the active item updates correctly when focus moves in from outside.
- CDK menu: reopening a menu uses the latest trigger data.
- CDK scrolling: a scrollable no longer leaks into nested lists.
- Aria menu: content renders only when visible, and the trigger’s tab index is exposed.
- Aria accordion and tree: no errors when destroyed before initialisation.
- Checkbox and radio: labels use the correct selector.
If you saw flaky keyboard behaviour in a combobox or odd menu state after reopening, test again after updating.
Upgrade checklist
- Run
ng update @angular/[email protected] @angular/[email protected]. - Replace
matChipAvataron<mat-icon>elements withmatChipLeadingIcon; keep avatars for images. - Make sure chips with icons still have readable text.
- Check custom chip code or tests that read
chip.leadingIcon. - Remove
::ng-deephacks for stepper icon shape and use the token. - Re-test keyboard navigation in comboboxes and menus.
Takeaway
Angular Material 22.3 is a small, safe upgrade. Chips finally get a real leading icon slot, steppers can change their icon shape through a token, and several keyboard and accessibility bugs are fixed. Update, swap avatar-as-icon hacks for matChipLeadingIcon, and enjoy cleaner templates.
