Stepper
A step-driven content panel: a clickable step header synced with content panels (only the current step is visible) — for wizards, multi-step forms and checkout flows. Two components work as a pair: oas-stepper manages the step header, oas-stepper-panel holds the content, associated by value (same pattern as oas-tabs / oas-tab-panel).
Basic usage
Pass the steps array via steps ({title, description?, icon?, disabled?, status?}, semantics aligned with oas-steps), associate content panels by index value, and point current at the active step.
Basic usage
Step 1: fill in the shipping address and order details.
Step 2: choose a payment method.
Step 3: wait for the seller to ship and confirm receipt.
Clickable steps
clickable is enabled by default: clicking an enabled step jumps to it (the whole step is clickable, keyboard Enter/Space works); clicking fires oas-change (detail is { index }) and writes back to current.
Click a step to switch
Order form area
Payment method area
Shipping progress area
Linear mode (no skipping)
With linear, only steps with index <= current can be activated: past steps can be revisited, the current step stays put, future steps are blocked (aria-disabled + visually weakened, silent on click/keyboard).
Linear mode (no skipping)
Profile form
Identity verification flow
Activation success message
Disabled steps
The per-step disabled field disables a step: not clickable, skipped by keyboard, visually weakened; an explicit status still displays normally.
Disabled step
Upload area
Face check area
Review result area (disabled)
Status marks
The per-step status field sets an explicit state: finish (success color + ✓) / error (danger color + ✕); otherwise it is derived from current (previous steps finish / current process / later steps wait).
finish / process / error / wait
Assets downloaded
Parsing data…
Parse failed, please retry
Flow finished
Vertical layout
direction="vertical" stacks the step header vertically (indicator on the left, title on the right, connector down the left side); content panels stay below.
Vertical steps
Profile form
ID upload
Review result
Panel linkage (controlled current)
current is two-way: clicking a step writes it back, external changes to current instantly sync aria-selected and panel visibility. Prev/next buttons are not built in — the host sets current with its own buttons.
External buttons control the step
Custom step content
The per-step icon field (an icon registry key) renders an icon at the indicator position (explicit icon takes priority over the status default); panel content goes through the default slot and can compose arbitrary content.
Icon steps + rich panels
Keyboard & accessibility
The header is role="tablist" with each step role="tab" (aria-selected / aria-disabled synced); panels are role="tabpanel" linked via aria-labelledby. Roving tabindex: Tab enters on the current step, arrow keys move focus between steps (horizontal ←/→, vertical ↑/↓, skipping disabled steps), Home/End jump to the first/last, Enter/Space activates.
Keyboard navigation
Focus is on step 1. Press → or Enter to try keyboard navigation.
Step 2 content
Step 3 content
Step 4 content
Size tiers
size has five tiers (xs / small / medium / large / xl) controlling title font density; invalid values fall back to medium with a dev warning.
size tiers
API
oas-stepper
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
clickable | Steps are clickable to jump (default true; clickable="false" disables: click/keyboard silent, arrow focus still works) | string | true |
current | Current step index (0-based, two-way: jumps write it back, external sets instantly sync aria-selected and panel visibility); invalid values fall back to 0, out-of-range clamped | string | 0 |
direction | Direction: horizontal (default) / vertical (indicator left / title right) | string | horizontal |
linear | Linear mode: only steps with index <= current can be activated (future steps aria-disabled + visually weakened, silent on click/keyboard) | boolean | — |
size | Size tier: xs/small/medium/large/xl (title font density; invalid values fall back to medium + dev warning, deduped) | string | medium |
steps | Steps data JSON [{ title, description?, icon?, disabled?, status? }] (semantics aligned with oas-steps StepItem minus panel-unrelated fields); invalid/empty fall back to [] | StepperStep[] | string | [] |
Events
| Event | Description |
|---|---|
oas-change | Fired when jumping to a clickable step (step click / keyboard Enter/Space); detail: { index } (0-based, bubbles + composed, writes back current) |
Slots
| Name | Description |
|---|---|
| default | Content panel projection area (<oas-stepper-panel> direct children); panels are associated with step indexes by value, only the one matching current is visible |
oas-stepper-panel
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
value | Step index string the panel is associated with (e.g. value="0"); only the panel matching current is visible (hidden driven by oas-stepper) | — | — |
Slots
| Name | Description |
|---|---|
| default | Panel content (default slot) |