---
name: steps-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Steps for
multi-step workflows using the Zag.js steps machine, compound list/items,
panels, progress, navigation triggers, linear flow, controlled step, and
variants.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux zag-compound-components app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/steps"
contributor_sources: "libs/ui/src/molecules/steps.tsx libs/ui/src/tokens/components/molecules/_steps.css libs/ui/stories/molecules/steps.stories.tsx libs/ui/src/molecules/steps.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Steps Usage
On narrow surfaces, horizontal triggers put their number above the label and
wrap longer copy. Vertical workflows stack the step list above panels and
navigation; their supplementary progress track becomes horizontal. From the
small breakpoint upward, vertical workflows use the side-by-side layout.
Use Steps for wizard/progress workflows. Use Tabs for peer panels, and
Pagination for page navigation.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Steps`.
**Use it when**
- Ordered multi-step tasks: checkout, onboarding, import wizards (3–7 steps).
**Use something else when**
| Need | Use instead |
| --- | --- |
| Peer views | Tabs |
| Pages of results | Pagination |
| Explaining existing UI | Tour |
**Do**
- Name each step with a short noun for its stage (`Shipping`, `Payment`, `Review`).
- Actions at the bottom: `Back` at the start, `Continue` at the end; the last step's button is the real action (`Place order`).
- Validate each step before continuing; let users go back without losing data.
- Allow jumping back to completed steps.
**Don't**
- Use more than ~7 steps; split the flow.
- Hide the global navigation choice to leave (focused layouts still offer a way out).
**Copy and states**
- Step titles are short nouns (see Do); progress text `Step 2 of 4` for assistive tech.
**Behaviour (from the UX spec)**
- Visited is not complete: a stage becomes complete only after its conditions passed; gate list jumps too (`isStepValid` or a gated controlled `onStepChange`).
- Going back keeps data but re-validates later stages the change may invalidate.
- Opening the summary is not submitting; the final step has its own named action and confirmation.
- Tasks that can be done in any order are a task list, not a linear Steps.
**Figma → code**
| Figma | Code |
| --- | --- |
| `appearance=subtle\|solid`, `size=sm…lg` | `appearance` (same values), `size` |
| current / complete / default | `step` / `defaultStep`; complete = steps before the current one |
| — | `linear`, `orientation` (not in Figma) |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Molecules/Steps → UX guidelines*.
## Setup
```tsx
const stages = [
{ title: "Cart", content: "Check products and quantities." },
{ title: "Delivery", content: "Confirm the delivery address." },
{ title: "Review", content: "Review the order before confirming." },
]
{stages.map((stage, index) => (
{stage.title}
))}
{stages.map((stage, index) => (
{stage.title}
{stage.content}
))}
Order confirmed
Your order is ready for processing.BackConfirm and continue
```
Supported props:
```text
count, step/defaultStep, linear, orientation horizontal | vertical
appearance: subtle | solid
size: sm | md | lg
onStepChange, onStepComplete
RootProvider/useSteps for external store
```
## Core Patterns
### Use for ordered workflows
Checkout, onboarding, setup, and import flows fit Steps.
### Keep item indexes aligned
`Steps.Item index` and `Steps.Content index` must match the intended step.
### Use navigation triggers
Use `PrevTrigger` and `NextTrigger` so disabled/completed state comes from the
machine.
## Common Mistakes
### HIGH Custom wizard state
Wrong:
```tsx
{step === 1 && }
```
Correct:
Use the complete Setup example: count, headers, panels and completion are derived together.
Source: libs/ui/src/molecules/steps.tsx
### HIGH Missing count
Wrong:
```tsx
```
Correct:
```tsx
{/* Partial root-prop illustration; include the complete anatomy from Setup. */}
{/* Setup list, panels and navigation */}
```
Source: https://zagjs.com/components/react/steps
### HIGH Inline progress styling
Wrong:
```tsx
```
Correct:
```tsx
```
Source: libs/ui/src/tokens/components/molecules/_steps.css
## Validation Commands
```sh
rg -P -n "setStep|]*count=)|]*className=.*(bg-|h-|rounded-)" apps
rg -P -n "]*index=)|]*index=)" apps
rg -n "