Navigation

Stepper

New

Copy page

View as Markdown

Open in ChatGPT

Open in Claude

Shows progress through a sequence of steps and the content of the current step.

Usage#

app.component.ts

import { WDS_STEPPER } from '@wds/angular/stepper';

Put wds-stepper-item elements (the steps) and, optionally, wds-stepper-panel elements (their content, in the same order) in wds-stepper. value is the active step, counted from 1; steps before it are completed. Name the stepper with aria-label.

Examples#

Default#

Steps are buttons: a click goes to the step and fires wds-change. Completed steps show a check mark.

Show code

stepper-default.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-default-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="2" class="w-full max-w-2xl" aria-label="Checkout">
      <wds-stepper-item heading="Cart"></wds-stepper-item>
      <wds-stepper-item heading="Shipping"></wds-stepper-item>
      <wds-stepper-item heading="Payment"></wds-stepper-item>
      <wds-stepper-item heading="Review"></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperDefaultDemo {}

Description#

description adds a line under the title.

Show code

stepper-description.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-description-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="2" class="w-full max-w-3xl" aria-label="Account setup">
      <wds-stepper-item heading="Account" description="Email and password"></wds-stepper-item>
      <wds-stepper-item heading="Profile" description="Name and photo"></wds-stepper-item>
      <wds-stepper-item heading="Team" description="Invite people"></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperDescriptionDemo {}

Wizard#

Panels show the content of the active step. Back and Next change value (or call previous() and next()); a value one past the last step marks all steps as completed.

Project name

Invite by email

Check the details and create the project.

Back

Show code

stepper-wizard.ts

import { Component, signal } from '@angular/core';
import { WdsButtonComponent } from '@wds/angular/button';
import { WDS_FIELD } from '@wds/angular/field';
import { WdsInputComponent } from '@wds/angular/input';
import { WdsStepperComponent, WdsStepperItemComponent, WdsStepperPanelComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-wizard-demo',
  imports: [...WDS_FIELD, WdsButtonComponent, WdsInputComponent, WdsStepperComponent, WdsStepperItemComponent, WdsStepperPanelComponent],
  template: `
    <div class="flex w-full max-w-2xl flex-col gap-6">
      <wds-stepper [value]="step()" linear aria-label="Create project" (wdsChange)="step.set($event.value)">
        <wds-stepper-item heading="Details" />
        <wds-stepper-item heading="Members" />
        <wds-stepper-item heading="Confirm" />
        <wds-stepper-panel>
          <wds-field>
            <wds-field-label>Project name</wds-field-label>
            <wds-input value="Website redesign" />
          </wds-field>
        </wds-stepper-panel>
        <wds-stepper-panel>
          <wds-field>
            <wds-field-label>Invite by email</wds-field-label>
            <wds-input type="email" placeholder="[email protected]" />
          </wds-field>
        </wds-stepper-panel>
        <wds-stepper-panel>
          <div class="text-sm text-muted-foreground">Check the details and create the project.</div>
        </wds-stepper-panel>
      </wds-stepper>
      <div class="flex justify-between">
        <wds-button variant="outline" [disabled]="step() === 1 || step() > count" (click)="step.set(step() - 1)">Back</wds-button>
        <wds-button [disabled]="step() > count" (click)="step.set(step() + 1)">
          {{ step() >= count ? 'Create project' : 'Next' }}
        </wds-button>
      </div>
    </div>
  `,
})
export class StepperWizardDemo {
  protected readonly count = 3;
  protected readonly step = signal(1);
}

Vertical#

orientation="vertical" stacks the steps; panels, if any, show next to them.

Show code

stepper-vertical.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-vertical-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="3" orientation="vertical" aria-label="Order status">
      <wds-stepper-item heading="Order placed" description="Oct 1, 9:14"></wds-stepper-item>
      <wds-stepper-item heading="Packed" description="Oct 1, 15:40"></wds-stepper-item>
      <wds-stepper-item heading="Shipped" description="With DHL, tracking 4429 1180"></wds-stepper-item>
      <wds-stepper-item heading="Delivered" description="Expected Oct 4"></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperVerticalDemo {}

Progress bar#

variant="bar" draws each step as a segment of a progress bar with the title below.

Show code

stepper-bar.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-bar-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="2" variant="bar" class="w-full max-w-2xl" aria-label="Onboarding">
      <wds-stepper-item heading="Workspace"></wds-stepper-item>
      <wds-stepper-item heading="Integrations"></wds-stepper-item>
      <wds-stepper-item heading="Invite team"></wds-stepper-item>
      <wds-stepper-item heading="Done"></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperBarDemo {}

Icons#

An icon in the icon slot replaces the number; completed steps still show the check mark.

Show code

stepper-icons.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-icons-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="2" class="w-full max-w-2xl" aria-label="Publishing">
      <wds-stepper-item heading="Write">
        <svg slot="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 20h9" /><path d="M16.4 3.6a2 2 0 0 1 2.9 2.9L7 18.8l-4 1 1-4Z" /></svg>
      </wds-stepper-item>
      <wds-stepper-item heading="Review">
        <svg slot="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2 12s3-7 10-7 10 7 10 7-3 7-10 7-10-7-10-7Z" /><circle cx="12" cy="12" r="3" /></svg>
      </wds-stepper-item>
      <wds-stepper-item heading="Publish">
        <svg slot="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m22 2-7 20-4-9-9-4Z" /><path d="M22 2 11 13" /></svg>
      </wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperIconsDemo {}

Loading and disabled#

loading shows a spinner in the circle, disabled blocks a step. readonly turns the steps into a progress display that cannot be clicked.

Show code

stepper-states.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-states-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="3" readonly class="w-full max-w-2xl" aria-label="Import">
      <wds-stepper-item heading="Upload"></wds-stepper-item>
      <wds-stepper-item heading="Map columns"></wds-stepper-item>
      <wds-stepper-item heading="Validate" loading></wds-stepper-item>
      <wds-stepper-item heading="Import" disabled></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperStatesDemo {}

Linear#

With linear only completed steps and the active one can be chosen; later steps open with Next.

Show code

stepper-linear.ts

import { Component } from '@angular/core';
import { WdsStepperComponent, WdsStepperItemComponent } from '@wds/angular/stepper';

@Component({
  selector: 'app-stepper-linear-demo',
  imports: [WdsStepperComponent, WdsStepperItemComponent],
  template: `
    <wds-stepper value="2" linear class="w-full max-w-2xl" aria-label="Application">
      <wds-stepper-item heading="Personal details"></wds-stepper-item>
      <wds-stepper-item heading="Experience"></wds-stepper-item>
      <wds-stepper-item heading="Documents"></wds-stepper-item>
      <wds-stepper-item heading="Submit"></wds-stepper-item>
    </wds-stepper>
  `,
})
export class StepperLinearDemo {}

API References#

wds-stepper#

Shows progress through a sequence of steps (a wizard, a checkout, an onboarding) and the content of the active step. Steps before the active one are completed. The steps are buttons that go to their step, unless the stepper is readonly; with linear only completed steps and the next one can be chosen.

Attributes

Attribute	Type	Default	Description
value	number	1	The active step, counted from 1. A value greater than the number of steps marks all steps as completed.
orientation	WdsStepperOrientation	'horizontal'	Layout: steps in a row, or in a column with the content next to them.
variant	WdsStepperVariant	'default'	`bar`: each step is a segment of a progress bar with its title below.
linear	boolean	false	Only completed steps and the one after them can be chosen.
readonly	boolean	false	The steps only show progress and cannot be clicked.

Events

Event	Description
wds-changeCustomEvent<WdsStepperChangeDetail>	The user chose a step (a click on a step).

Methods

Method	Description
next()	Goes to the next step.
previous()	Goes to the previous step.
goTo(step: number)	Goes to a step (from 1; the number of steps + 1 marks all as completed).

Slots

Slot	Description
(default)	`wds-stepper-item` elements (the steps) and `wds-stepper-panel` elements (their content, in the same order).

CSS custom properties

Property	Description
--wds-stepper-indicator-size	Size of the step circles (default 32px).

wds-stepper-item#

One step of wds-stepper: a numbered circle (a check mark when completed, a spinner while loading, or your icon), a title and an optional description, and a line to the next step. The stepper sets its number and state.

Attributes

Attribute	Type	Default	Description
heading	string	''	Title of the step.
description	string	''	Description under the title.
completed	boolean	false	Marks the step as completed even when it is after the active one.
disabled	boolean	false	The step cannot be chosen.
loading	boolean	false	Shows a spinner in the circle (e.g. while the step is being saved).

Slots

Slot	Description
icon	An icon in the circle instead of the number (the check mark still shows when completed).
title	Title (instead of `heading`).
description	Description (instead of `description`).

CSS parts (::part)

Part	Description
trigger	The step: a native `<button>`, or a `<div>` when it cannot be chosen.
indicator	The circle (or the bar segment with `variant="bar"`).
title	The title.
description	The description.
separator	The line to the next step.

wds-stepper-panel#

Content of one step in wds-stepper. Panels follow the steps in order: the first panel belongs to the first step. Only the panel of the active step is visible. It is a group named by the step's title.

Slots

Slot	Description
(default)	Content of the step (e.g. form fields).

Accessibility#

The stepper is a group; name it with aria-label. Each step is a button (a plain element with readonly) with aria-current="step" on the active one.

Every step is read with its position and state, e.g. "Step 2 of 4, current: Shipping", so the progress does not depend on color or the check mark.

A panel is a group named by the title of its step. After Next, move focus to the first field of the new panel if the user continues typing there.

Keyboard support#

Key	Function
Tab	Moves focus to the next step that can be chosen, then into the active panel.
Enter	Goes to the focused step.
Space	Goes to the focused step.

Usage#

Examples#

Default#

Description#

Wizard#

Vertical#

Progress bar#

Icons#

Loading and disabled#

Linear#

API References#

wds-stepper#

Attributes

Events

Methods

Slots

CSS custom properties

wds-stepper-item#

Attributes

Slots

CSS parts (::part)

wds-stepper-panel#

Slots

Accessibility#

Screen reader#

Keyboard support#