Stepper
Controlled workflow progress with horizontal and vertical layouts, linear navigation, and explicit status communication.
- Selector
- ui-stepper
- Package
- @ngnova/ui/stepper
Import
import { UiStepperComponent } from '@ngnova/ui/stepper';Usage & variants
Live examples use the public ui-stepper API, paired with the exact snippet a product team would paste into an Angular app.
Release workflow
Controlled workflow progress with horizontal and vertical layouts, linear navigation, and explicit status communication.
Production guidance
Use these notes to decide when the component belongs in a product workflow and what to verify before shipping.
When to use
Use for workflows with meaningful ordered stages, such as onboarding, checkout, publishing, or account setup.
Watch for
An empty collection renders projected content without an incorrectly named region.
Product recipes
Apply Stepper in distinct, copyable product scenarios—not just an isolated component state.
Controlled release workflow
The parent validates the active panel and advances it; the header can provide direct or backward-only navigation.
1 2 3 4 5 6 7 8
<ui-stepper
[steps]="releaseSteps"
[(active)]="activeStep"
[linear]="true"
ariaLabel="Release workflow"
>
<app-release-step [step]="activeStep" />
</ui-stepper>Vertical compact workflow
Vertical orientation keeps descriptions readable in narrow layouts.
1 2 3 4 5
<ui-stepper
orientation="vertical"
[steps]="onboardingSteps"
[(active)]="activeStep"
/>API Reference
Inputs and outputs are semver-sensitive public API. Keep examples aligned with this table.
Inputs
id generated string Stable base ID for step and active-panel relationships.
steps [] readonly UiStepItem[] Ordered workflow steps with value, label, and optional description, completion, error, optional, and disabled metadata.
active '' string Controlled value of the current step; falls back to the first enabled step.
ariaLabel 'Progress' string Accessible name for the workflow navigation landmark.
orientation 'horizontal' 'horizontal' | 'vertical' Visual orientation of steps and connectors.
linear false boolean Restricts header navigation to prior steps so the application validates forward progress.
interactive true boolean Allows non-current eligible steps to act as navigation controls.
| Name | Type | Default | Description |
|---|---|---|---|
id | string | generated | Stable base ID for step and active-panel relationships. |
steps | readonly UiStepItem[] | [] | Ordered workflow steps with value, label, and optional description, completion, error, optional, and disabled metadata. |
active | string | '' | Controlled value of the current step; falls back to the first enabled step. |
ariaLabel | string | 'Progress' | Accessible name for the workflow navigation landmark. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Visual orientation of steps and connectors. |
linear | boolean | false | Restricts header navigation to prior steps so the application validates forward progress. |
interactive | boolean | true | Allows non-current eligible steps to act as navigation controls. |
Outputs
activeChange OutputEmitterRef<string> Emits the requested controlled active value.
stepSelected OutputEmitterRef<UiStepperSelection> Emits the selected step and its source index.
| Name | Type | Description |
|---|---|---|
activeChange | OutputEmitterRef<string> | Emits the requested controlled active value. |
stepSelected | OutputEmitterRef<UiStepperSelection> | Emits the selected step and its source index. |
Accessibility
- A named nav landmark and ordered list communicate the workflow structure without assigning tab semantics.
- The active item uses aria-current="step" and labels the projected content region through stable IDs.
- Status is exposed through text and structure rather than color alone; selectable steps receive contextual accessible names.
Keyboard behavior
- Selectable steps use native buttons and follow normal Tab and activation behavior.
- Linear mode removes future steps from the tab sequence while preserving their visible progress information.
Testing guidance
- Use UiStepperHarness to inspect labels, states, current step, orientation, projected panel, and selectable navigation.
- Test controlled selection, linear restrictions, fallback active values, disabled steps, errors, optional steps, both orientations, and empty state.