skip to content

A publish wizard built by extending the Angular CDK's `CdkStepper` fails with 'No provider found for CdkStepper' from its `<cdk-step>` children; why, and what else must the subclass supply?

level: seniorimportance: should knowfreq 28%

answer

  1. children inject the parent by token
  2. useExisting under the base class
  3. selected step's content is a TemplateRef
  4. headers, ARIA and keys are yours
  5. cdkStepperNext defaults to submit

basics

~20 s

CdkStep and the cdkStepperNext and cdkStepperPrevious buttons inject CdkStepper, but a subclass component is registered under its own class. Provide CdkStepper with useExisting pointing at the subclass, then supply the template: step content, headers, navigation and ARIA.

solid answer

~40 s

Each `cdk-step` runs `inject(CdkStepper)` to find its stepper, and so do `cdkStepperNext` and `cdkStepperPrevious`. Extending the class does not register the subclass under the `CdkStepper` token, so Angular throws its no-provider error (NG0201) until the component declares `providers: [{provide: CdkStepper, useExisting: PublishWizard}]`. After that, the subclass owns everything visible: each step's content is a `TemplateRef` that you render with `[ngTemplateOutlet]="selected?.content"`, plus the header row and navigation buttons. The CDK stepper applies almost no ARIA; its guide recommends `role="tablist"`, `role="tab"` with `aria-selected`, and `role="tabpanel"`. Validation comes from `linear` with each step's `stepControl` or `completed`, `editable="false"` blocks returning, and `cdkStepperNext` defaults to `type="submit"`, so set `type="button"` inside a shared form.

go deeper

for a junior

Recall the pieces: a component extending CdkStepper, cdk-step children, and cdkStepperNext and cdkStepperPrevious buttons.

for a middle

Explain token-based injection: children inject CdkStepper, so the subclass must alias itself with useExisting, and the selected step's content is a TemplateRef you render.

for a senior

Build the whole wizard: headers with tab semantics, linear validation through stepControl, non-editable steps, the submit default on cdkStepperNext, and a deliberate reset.

for a principal

Weigh subclassing CdkStepper, and its reliance on internal wiring for arrow keys, against adopting mat-stepper when the Material 3 look is acceptable.

## What `CdkStepper` is `CdkStepper` (from `@angular/cdk/stepper`) is the **behaviour base** of a wizard: it tracks which step is selected, validates progress in linear mode, exposes `next()`, `previous()`, `reset()`, `selectedIndex` and `selectionChange`, and manages keyboard focus across step headers. Angular Material's `mat-stepper` extends it. To build an unbranded **multi-step publish wizard** (details, audience, schedule, confirm) for a document editor, you extend it in your own component, as the components repository guide on creating a custom stepper shows. ## Why the children cannot find the stepper Angular's injector resolves dependencies **by token**. `CdkStep` declares `_stepper = inject(CdkStepper)`, and the `cdkStepperNext` and `cdkStepperPrevious` button directives do the same. A component declared as `class PublishWizard extends CdkStepper` is registered on its element under the token `PublishWizard`. Inheritance does not add the parent class as a second token, so lookups for `CdkStepper` walk past it and fail with NG0201, "No provider found for CdkStepper". The fix is an **alias provider**: ```ts import {Component} from '@angular/core'; import {NgTemplateOutlet} from '@angular/common'; import {CdkStepper, CdkStepperNext, CdkStepperPrevious} from '@angular/cdk/stepper'; @Component({ selector: 'app-publish-wizard', imports: [NgTemplateOutlet, CdkStepperNext, CdkStepperPrevious], providers: [{provide: CdkStepper, useExisting: PublishWizard}], templateUrl: './publish-wizard.html', }) export class PublishWizard extends CdkStepper {} ``` `useExisting` makes the token resolve to the **same instance**, not a second stepper. In v22 `CdkStepper` gets its own dependencies through `inject()`, so the subclass needs no constructor and passes nothing to `super()`. ## What the subclass template must supply The base class renders nothing visible. Each `<cdk-step>` wraps its projected content in an `ng-template` and exposes it as `content`, a `TemplateRef`. Your template decides: 1. **The panel**: render `selected?.content` with `ngTemplateOutlet`. 2. **The headers**: loop over `steps` and show each step's `label`, selected state, completion and errors. 3. **Navigation**: `cdkStepperNext` and `cdkStepperPrevious` buttons, or calls to `next()`, `previous()` and setting `selectedIndex`. 4. **Accessibility**: the CDK guide says that, apart from keyboard support, the stepper applies no treatment. It recommends a `role="tablist"` header container, `role="tab"` headers with `aria-selected`, and `role="tabpanel"` content. `cdkStepHeader` puts `role="tab"` on a header, and the stepper's arrow-key focus handling walks the elements marked with it. Material's own stepper template also forwards header keydown events to the stepper's underscore-prefixed `_onKeydown` handler, an internal method, so a custom template that wants the built-in arrow keys copies that wiring and accepts the version risk. 5. **Styles**: all of them. ## Linear mode and step state | Setting | On | Effect | |---|---|---| | `linear` | stepper | forward moves require earlier steps to be complete | | `stepControl` | `cdk-step` | an `AbstractControl` (or a signal-forms field) whose validity decides completeness | | `completed` | `cdk-step` | manual completeness when there is no form | | `optional` | `cdk-step` | the step never blocks linear progress | | `editable` | `cdk-step` | `false` stops the user returning once past it | Without an override, a step counts as `completed` once the user has interacted with it (tried to leave it) and its `stepControl`, if any, is valid. The guide says `stepControl` wins when both are set. The v22.2.1 source is more specific: an explicit `completed` of `false` leaves the decision to `stepControl`, but an explicit `true` lets linear navigation pass even when the control is invalid. ## The submit trap `cdkStepperNext` declares a `type` input that defaults to **`"submit"`**, while `cdkStepperPrevious` defaults to `"button"`. If one form wraps the whole wizard, every Next press also submits it. The CDK guide's advice for a single form is to make intermediate buttons `type="button"`. With one form per step, submitting a step's form is what advances the wizard. ## Resetting `reset()` returns to the first step and resets every step, including its form control, which clears the entered values. Call it after a successful publish, not on cancel if drafts should survive. ## Where Material fits `mat-stepper` extends `CdkStepper` and `mat-step` extends `CdkStep`, so everything above, including linear mode, `editable` and `reset()`, behaves identically there; Material adds the header markup, ARIA roles, keyboard wiring and Material 3 styles. Both read the `STEPPER_GLOBAL_OPTIONS` token, whose `showError` and `displayDefaultIndicatorType` options change how step errors and indicators are computed. If the wizard can look like Material, adopting `mat-stepper` removes the subclass entirely. ## Common mistakes - Forgetting the alias provider and blaming module imports. - Rendering every step's content at once and hiding inactive steps with opacity or off-screen positioning, which leaves their fields in the tab order. - Assuming the base class ships header markup or Material styling.

  • How do you stop authors from going back to change the audience once the wizard has moved past it?
    Set `editable="false"` on that `cdk-step`. When `selectedIndex` is asked to move to an earlier index, `CdkStepper` only allows it if the target step is editable. Combine it with `linear` and a `stepControl` so the step must also be valid before anyone moves forward.
  • Why does the publish wizard's Next button submit the whole document form?
    `cdkStepperNext` binds its `type` input to the button and defaults it to `submit`, so inside a form that wraps every step it submits the form as well as advancing. Write `type="button"` on it. `cdkStepperPrevious` already defaults to `button`.

  • Extending CdkStepper registers the subclass under the CdkStepper token
  • CdkStepper ships default header markup and styles you can theme
  • cdkStepperNext defaults to type button, so it never submits a form
  • A CdkStepper subclass must pass injected services to super()
  • Each cdk-step renders its own content; the subclass only adds buttons