Spartan Stepper

Components / Stepper

Stepper

A composable Angular stepper built on the CDK and styled with Spartan primitives. It supports linear flows, horizontal and vertical layouts, custom labels, indicator modes, validation, and lazy step content.

Preview

A simple horizontal stepper with plain content and step-owned navigation actions.

  1. Step One
  2. Step Two
  3. Step Three
Content 1

Installation

This repo exposes the stepper as local primitives. Import the stepper bundle and the Spartan button styles you want to use inside each step.

Imports
import { HlmButtonImports } from '../libs/button/src';
import { HlmStepperImports } from '../stepper';

@Component({
  imports: [HlmStepperImports, HlmButtonImports],
})

Usage

Use hlm-stepper as the container, hlm-step for each step, and the navigation directives on buttons inside the active panel.

Template
<hlm-stepper [linear]="true" indicatorMode="state">
  <hlm-step [stepControl]="accountForm" label="Account">
    <form [formGroup]="accountForm" class="flex flex-col gap-4">
      <!-- fields -->

      <div class="flex justify-end">
        <button hlmBtn hlmStepperNext>Next</button>
      </div>
    </form>
  </hlm-step>

  <hlm-step label="Review">
    <div class="flex justify-between gap-2">
      <button hlmBtn variant="outline" hlmStepperPrevious>Back</button>
      <button hlmBtn>Submit</button>
    </div>
  </hlm-step>
</hlm-stepper>

Examples

Examples of different stepper configurations and features. The CDK's flexible foundation means you can build whatever flow you need on top of the Spartan-rendered header and indicators.

Layout

Keep the stepper horizontal while changing labelPosition and headerPosition.

  1. Overview
  2. Preferences Optional
  3. Done

This example focuses on the horizontal layout controls: labelPosition and headerPosition.

Vertical

Use vertical orientation when content is dense or when each step panel needs more inline space.

Campaign

Use the vertical orientation when content is dense or the available horizontal space is limited.

Responsive

Switches from horizontal to vertical orientation on small screens to reduce horizontal overflow.

  1. Campaign
  2. Audience
  3. Review

This example switches to vertical orientation below 768px.

RTL (Arabic)

Demonstrates both horizontal and vertical steppers with dir="rtl" and Arabic labels/content.

أفقي

  1. الحساب
  2. العنوان
  3. المراجعة
المحتوى ١

عمودي

المرحلة الأولى
هذا مثال للعرض العمودي من اليمين إلى اليسار.

Indicator Modes

Render numeric indicators, CDK state icons, or per-step custom icons.

Number

Always renders 1, 2, 3.

  1. Profile
  2. Address
  3. Done
Number indicator content

State

Default Material-like state icons for completion and errors.

  1. Profile
  2. Address
  3. Done
State indicator content

Icon

Per-step icons only when indicatorMode="icon" is enabled.

  1. Profile
  2. Address
  3. Contact
Icon indicator content

States

Mark steps as completed, optional, or non-editable without changing the overall API.

  1. Completed
  2. Optional Optional
  3. Locked After Complete

Completed steps render the state indicator and remain navigable in non-linear mode.

Validation

In linear mode, moving forward marks the current form touched and blocks navigation until it becomes valid.

  1. Identity
  2. Security
  3. Review

Error State

Similar to Angular Material, a non-linear stepper can show header errors after the user moves past an invalid step when STEPPER_GLOBAL_OPTIONS enables showError.

  1. Contact
  2. Review

This example is intentionally non-linear. Click next without filling the field to move forward and trigger the header error state.

Lazy Content

Use hlmStepContent to defer expensive step panels until the user reaches them.

  1. Overview
  2. Analytics
  3. Summary

The first step renders immediately. Later steps use hlmStepContent so their bodies are attached lazily.

Helm API

hlm-stepper is built on top of CdkStepper. The tables below separate the Spartan-specific API from the inherited CDK contracts you still use when building flows.

Foundation

The Angular CDK owns the workflow logic: step registration, selection state, keyboard interactions, linear validation flow, and the base navigation directives. Spartan adds the rendered header, indicator options, and layout styling on top of that foundation. Global CDK behavior such as STEPPER_GLOBAL_OPTIONS.showError still applies to hlm-stepper.

Spartan Additions

SelectorInputs
hlm-stepperlabelPosition, headerPosition, indicatorMode

Inherited CDK Stepper API

SelectorInputs
hlm-stepper via CdkStepperlinear, orientation, selectedIndex, selected, steps, next(), previous(), reset()
hlm-step via CdkSteplabel, stepControl, completed, optional, editable, hasError, errorMessage, state, aria-label, aria-labelledby, icon

Directives

DirectivePurpose
button[hlmStepperNext]Moves to the next step.
button[hlmStepperPrevious]Moves to the previous step.
[hlmStepLabel]Provides a template label instead of a plain string.
ng-template[hlmStepContent] Attaches step content lazily when the step is selected.

The navigation directives wrap the CDK equivalents CdkStepperNext and CdkStepperPrevious, while hlmStepLabel and hlmStepContent mirror the CDK and Material template patterns for custom labels and lazy step content.