From 4e09dc128e662368b4ca94f6d22c92f92cd53645 Mon Sep 17 00:00:00 2001
From: Kristiyan Kostadinov <crisbeto@abv.bg>
Date: Fri, 24 Apr 2026 10:21:01 +0200
Subject: [PATCH] fix(material/stepper): allow stepper to be labelled

Fixes that users didn't have a way to label the stepper after we changed the internal roles.

Fixes #33130.
---
 goldens/material/stepper/index.api.md |  3 ++-
 src/material/stepper/stepper.html     | 12 +++++++-----
 src/material/stepper/stepper.spec.ts  | 27 +++++++++++++++++++++++++--
 src/material/stepper/stepper.ts       |  6 ++++++
 4 files changed, 40 insertions(+), 8 deletions(-)

diff --git a/goldens/material/stepper/index.api.md b/goldens/material/stepper/index.api.md
index 346224f47d6a..3ec089342637 100644
--- a/goldens/material/stepper/index.api.md
+++ b/goldens/material/stepper/index.api.md
@@ -113,6 +113,7 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
     readonly animationDone: EventEmitter<void>;
     get animationDuration(): string;
     set animationDuration(value: string);
+    ariaLabel: string | null;
     color: ThemePalette;
     disableRipple: boolean;
     // (undocumented)
@@ -135,7 +136,7 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
     readonly steps: QueryList<MatStep>;
     _steps: QueryList<MatStep>;
     // (undocumented)
-    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "disableRipple": { "alias": "disableRipple"; "required": false; }; "color": { "alias": "color"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "headerPrefix": { "alias": "headerPrefix"; "required": false; "isSignal": true; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MatStepper, "mat-stepper, mat-vertical-stepper, mat-horizontal-stepper, [matStepper]", ["matStepper", "matVerticalStepper", "matHorizontalStepper"], { "disableRipple": { "alias": "disableRipple"; "required": false; }; "color": { "alias": "color"; "required": false; }; "labelPosition": { "alias": "labelPosition"; "required": false; }; "headerPosition": { "alias": "headerPosition"; "required": false; }; "ariaLabel": { "alias": "aria-label"; "required": false; }; "headerPrefix": { "alias": "headerPrefix"; "required": false; "isSignal": true; }; "animationDuration": { "alias": "animationDuration"; "required": false; }; }, { "animationDone": "animationDone"; }, ["_steps", "_icons"], ["*"], true, never>;
     // (undocumented)
     static ɵfac: i0.ɵɵFactoryDeclaration<MatStepper, never>;
 }
diff --git a/src/material/stepper/stepper.html b/src/material/stepper/stepper.html
index 1d281f98657f..fbb58e7f27cb 100644
--- a/src/material/stepper/stepper.html
+++ b/src/material/stepper/stepper.html
@@ -55,8 +55,9 @@
             class="mat-vertical-content-container"
             [class.mat-stepper-vertical-line]="!$last"
             [class.mat-vertical-content-container-active]="selectedIndex === $index"
-            [attr.inert]="selectedIndex === $index ? null : ''">
-            <div 
+            [attr.inert]="selectedIndex === $index ? null : ''"
+            [attr.aria-label]="ariaLabel">
+            <div
               class="mat-vertical-stepper-content"
               role="region"
               [id]="_getStepContentId($index)"
@@ -105,10 +106,11 @@
 </ng-template>
 
 <ng-template #horizontalStepsTemplate let-steps="steps">
-  <div 
+  <div
     aria-orientation="horizontal"
-    class="mat-horizontal-stepper-header-container" 
-    role="tablist">
+    class="mat-horizontal-stepper-header-container"
+    role="tablist"
+    [attr.aria-label]="ariaLabel">
     @for (step of steps; track step) {
       <ng-container
         [ngTemplateOutlet]="stepTemplate"
diff --git a/src/material/stepper/stepper.spec.ts b/src/material/stepper/stepper.spec.ts
index be1ddb1a0582..cfb7b1f12d03 100644
--- a/src/material/stepper/stepper.spec.ts
+++ b/src/material/stepper/stepper.spec.ts
@@ -1017,6 +1017,15 @@ describe('MatStepper', () => {
       expect(headers[2].classList.contains('mat-primary')).toBe(true);
       expect(headers[1].classList.contains('mat-accent')).toBe(true);
     });
+
+    it('should set an aria label on the content container', () => {
+      const fixture = createComponent(SimpleMatVerticalStepperApp);
+      fixture.componentInstance.ariaLabel.set('My Stepper');
+      fixture.detectChanges();
+
+      const container = fixture.nativeElement.querySelector('.mat-vertical-content-container');
+      expect(container.getAttribute('aria-label')).toBe('My Stepper');
+    });
   });
 
   describe('horizontal stepper', () => {
@@ -1217,6 +1226,17 @@ describe('MatStepper', () => {
 
       expect(stepperHost.classList).toContain('mat-stepper-header-position-bottom');
     });
+
+    it('should set an aria-label on the header container', () => {
+      const fixture = createComponent(SimpleMatHorizontalStepperApp);
+      fixture.componentInstance.ariaLabel.set('My Stepper');
+      fixture.detectChanges();
+
+      const container = fixture.nativeElement.querySelector(
+        '.mat-horizontal-stepper-header-container',
+      );
+      expect(container.getAttribute('aria-label')).toBe('My Stepper');
+    });
   });
 
   describe('linear stepper with valid step', () => {
@@ -1849,7 +1869,8 @@ class MatHorizontalStepperWithErrorsApp {
     <mat-stepper
       [disableRipple]="disableRipple()"
       [color]="stepperTheme()"
-      [headerPosition]="headerPosition()">
+      [headerPosition]="headerPosition()"
+      [aria-label]="ariaLabel()">
       <mat-step>
         <ng-template matStepLabel>Step 1</ng-template>
         Content 1
@@ -1881,6 +1902,7 @@ class MatHorizontalStepperWithErrorsApp {
 class SimpleMatHorizontalStepperApp {
   @ViewChild(MatStepper) stepper!: MatStepper;
   inputLabel = 'Step 3';
+  ariaLabel = signal<string | null>(null);
   disableRipple = signal(false);
   stepperTheme = signal<ThemePalette>(undefined);
   secondStepTheme = signal<ThemePalette>(undefined);
@@ -1889,7 +1911,7 @@ class SimpleMatHorizontalStepperApp {
 
 @Component({
   template: `
-    <mat-stepper orientation="vertical" [disableRipple]="disableRipple()" [color]="stepperTheme()">
+    <mat-stepper orientation="vertical" [disableRipple]="disableRipple()" [color]="stepperTheme()" [aria-label]="ariaLabel()">
       <mat-step>
         <ng-template matStepLabel>Step 1</ng-template>
         Content 1
@@ -1923,6 +1945,7 @@ class SimpleMatHorizontalStepperApp {
 class SimpleMatVerticalStepperApp {
   @ViewChild(MatStepper) stepper!: MatStepper;
   inputLabel = signal('Step 3');
+  ariaLabel = signal<string | null>(null);
   showStepTwo = signal(true);
   disableRipple = signal(false);
   stepperTheme = signal<ThemePalette>(undefined);
diff --git a/src/material/stepper/stepper.ts b/src/material/stepper/stepper.ts
index db4cfb1e34bf..c6635e9c5ed9 100644
--- a/src/material/stepper/stepper.ts
+++ b/src/material/stepper/stepper.ts
@@ -188,6 +188,12 @@ export class MatStepper extends CdkStepper implements AfterViewInit, AfterConten
   @Input()
   headerPosition: 'top' | 'bottom' = 'top';
 
+  /**
+   * ARIA label for the stepper.
+   */
+  @Input('aria-label')
+  ariaLabel: string | null = null;
+
   /** The content prefix to use in the stepper header. */
   readonly headerPrefix = input<TemplateRef<unknown> | null>(null);