--- name: Steps type: ATM section: navigation why: Ordered list of process steps with aria-current="step" on the active one. when: Multi-step flows: wizards, checkout, onboarding progress. where: dist/components/steps/steps.css supportedStates: default --- # Steps ## Native basis `

Account

Create credentials
2

Profile

Personal details
3

Complete

Review & confirm

Account

Create credentials
2

Profile
3

Complete

Account
Profile

Please fix the errors
3

Complete

1

Account
2

Profile
3

Complete

` for a glyph a size up; `data-variant="plain"` on the `.step-indicator` drops the circle (a symbol or icon there takes the step's color). ```html

😍

Loving it

``` For many steps in a narrow space, wrap the list in `overflow-x-auto` and give it a `min-width` - it scrolls instead of squeezing. --- ## Sizes | `data-size` | Indicator | Title font | Description font | |-------------|-----------|------------|------------------| | `xs` | 1.25rem | 0.6875rem | 0.625rem | | `sm` | 1.5rem | 0.75rem | 0.6875rem | | `md` | 2rem | 0.8125rem | 0.75rem | | *(none)* | 2rem | 0.8125rem | 0.75rem | | `lg` | 2.5rem | 0.9375rem | 0.8125rem | | `xl` | 3rem | 1.0625rem | 0.875rem | Connector offsets follow the indicator size in both orientations; `md` equals the unsized default. --- ## Density Set `data-density` on the `.steps` root; the flex gaps scale - the size ladder keeps owning indicator size and typography, so size and density combine freely. | Value | Effect | | --- | --- | | `compact` | Step gap 0.375rem, content gap 0.0625rem | | `comfortable` | Gaps 0.5rem / 0.125rem - identical to the unsized default | | `spacious` | Gaps 0.75rem / 0.25rem | ## States | `data-status` | Indicator | Connector | |---------------|-----------|-----------| | `complete` | Primary fill, white text/checkmark | Primary color line | | `current` | Primary border, primary text | Default border color | | `error` | Destructive fill, destructive-foreground text | Destructive color line | | *(none)* | Border only, muted text | Default border color | --- ## API ### States type StepsState = 'default' - `setState(name, config)` takes the config of the state it names (`StepsStateConfigs[name]`). | State | Description | |---|---| | `default` | The tracker at a step. config

Field	Type	Description
`activeStep?`	`number`	the current step, 1-based
`step?`	`number`	the same as activeStep (when activeStep is not given)
`page?`	`number`	the same as activeStep (when neither is given)
`errorStep?`	`number`	the step marked as failed, 0 for none
`activeStepError?`	`boolean`	true marks the current step as failed, false clears that
`size?`	`'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl'`	the size

| ### Every element | Member | Description | |---|---| | el.api.setState<S extends StepsState>(name: S, config?: StepsStateConfigs[S]): unknown | Enter a state: the DOM work runs (also when it is the current state), the store records it.

Argument	Type	Description
`name`	`S`	a declared state (an unknown name throws)
`config?`	`StepsStateConfigs[S]`	that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (or await settled()) | | el.api.getState(): { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel } | The state the element shows now - read back from the DOM, so it includes what the user changed. Returns { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from | | el.api.render(state?: { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel }): string | The element's markup in a state - the authored markup with that state applied; a pure function of the state.

Argument	Type	Description
`state?`	`{ name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel }`	a state as getState() returns it (default: the current one)

Returns string - the element's outer HTML in that state | | el.api.settled(): Promise<void> | Wait for the last state's DOM work (async states: a diagram rendering, a chart mounting). Returns Promise<void> - resolves when nothing is pending | | el.store: Store<{ name: StepsState; config: StepsStateConfigs[StepsState] }> | A defuss-store store of the element's state - subscribe to follow every change (also the user's), set it to drive the component. | ### Registry | Member | Description | |---|---| | df$.shadcn.stepsApi.setState<S extends StepsState>(el: HTMLElement, name: S, config?: StepsStateConfigs[S]): unknown | Enter a state: the DOM work runs (also when it is the current state), the store records it.

Argument	Type	Description
`el`	`HTMLElement`	the component's element
`name`	`S`	a declared state (an unknown name throws)
`config?`	`StepsStateConfigs[S]`	that state's config (merged into the stored one when the component merges)

Returns unknown - what the state's DOM work returned - a Promise for an async state (await it, or el.api.settled()) | |

df$.shadcn.stepsApi.getState(el: HTMLElement): { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel }

| The state the element shows now - read back from the DOM, so it includes what the user changed.

Argument	Type	Description
`el`	`HTMLElement`	the component's element

Returns { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel } - the state's name, its config and the authored markup model render() starts from | |

df$.shadcn.stepsApi.render(state: { name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel }): string

| The element's markup in a state - the authored markup with that state applied; a pure function of the state.

Argument	Type	Description
`state`	`{ name: StepsState; config: StepsStateConfigs[StepsState]; model?: ElementModel }`	a state as getState() returns it (with its model)

Returns string - the element's outer HTML in that state | | df$.shadcn.stepsApi.store(el: HTMLElement): Store<{ name: StepsState; config: StepsStateConfigs[StepsState] }> | The element's store (bindComponent made it).

Argument	Type	Description
`el`	`HTMLElement`	the component's element

Returns Store<{ name: StepsState; config: StepsStateConfigs[StepsState] }> - a defuss-store store of { name, config } - subscribe to follow every change, set it to drive the component | | df$.shadcn.stepsApi.commit<S extends StepsState>(el: HTMLElement, name: S, config?: StepsStateConfigs[S]): void | Record a state the element reached on its own (no DOM work) - for a component's own handlers.

Argument	Type	Description
`el`	`HTMLElement`	the component's element
`name`	`S`	the state it is in
`config?`	`StepsStateConfigs[S]`	its config

| | df$.shadcn.stepsStates: StepsState[] | The declared states, 'default' first: default. | --- ## ARIA | Attribute | Element | Purpose | |-----------|---------|---------| | `aria-current="step"` | Current `

` | Identifies the active step for screen readers | | `aria-hidden="true"` | Checkmark/X `

` | Marks the step as invalid for screen readers | --- ## Keyboard This component is CSS-only and does not manage keyboard interaction by default. When steps are made clickable: - Add `data-clickable` to the `

` element and `role="button" tabindex="0"` to the `.step-indicator` - Handle `click` and `keydown` (Enter/Space) in your own JavaScript to navigate between steps - Manage focus appropriately when the active step changes --- ## Notes - Use `

` alongside `data-status="error"`. - No JavaScript required - this is a CSS-only component. Step state is set via `data-status` attributes.