---
title: Steps
description: A sequence of steps that shows progress through a flow.
category: Navigation
status: beta
since: 0.3.4
tags: [steps, progress, workflow]
syncStatus: reviewed
verified: true
---

## Usage

### Numeric and String Keys
Numeric keys infer completed steps from `active`; string keys need an explicit `status`.
::::TuffDemoWrapper{demo="StepsStepsDemo" code-lang="vue"}
---
code: |
  <template>
    <TxSteps :active="1">
      <TxStep title="Start" description="Collect basics" :step="0" />
      <TxStep title="Details" description="Fill in details" :step="1" />
      <TxStep title="Finish" description="Review and submit" :step="2" />
    </TxSteps>

    <TxSteps direction="vertical" size="small" active="review">
      <TxStep title="Draft" description="Content saved" step="draft" status="completed" />
      <TxStep title="Review" description="Waiting for approval" step="review" icon="i-carbon-in-progress" />
      <TxStep title="Publish" description="Unlocked after review" step="publish" disabled />
    </TxSteps>
  </template>
---
::::

### Best Practices

- Use numeric keys for linear forms and onboarding so completion is inferred.
- Use string keys for named workflows, and set `completed` or `error` status explicitly.
- Disable steps that depend on unfinished prerequisites.
- Keep the authoritative flow state in the parent; `TxSteps` is a progress cue, not the source of truth for a router or form.
- Keep step descriptions short; put paragraphs or controls below the steps.

## API Reference

### TxSteps

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `active` | `number \| string` | `0` | Active step key; changes sync to the internal state. |
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Size, passed down to child steps. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `default` | - | `TxStep` children. |

### TxStep

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | - | Step title. |
| `description` | `string` | - | Supporting text. |
| `icon` | `string` | - | Icon name or class shown before completion. |
| `status` | `'wait' \| 'active' \| 'completed' \| 'error'` | `'wait'` | Manual status; the active state and numeric completion take precedence. |
| `step` | `number \| string` | child order | Step key; defaults to the zero-based child order. String keys are numbered by order. |
| `clickable` | `boolean` | `true` | Renders a button head; a click updates the internal active step. |
| `disabled` | `boolean` | `false` | Disables the step button and blocks activation. |
| `showLine` | `boolean` | `true` | Renders the connector; the last step never has one. |
| `completedIcon` | `string` | `'check'` | Icon shown in the completed state. |

## Overview

- `TxSteps` is `role="list"` and each `TxStep` is `role="listitem"`; the active step's head has `aria-current="step"`.
- A clickable head is a native `<button type="button">`, otherwise a `<div>`; a disabled step disables the button and ignores activation.
- A click only updates the active step inside `TxSteps`; nothing is emitted and the parent isn't updated.
- Numeric keys before a numeric `active` count as completed; string keys need `status="completed"`.
- Without `step`, a step registers in child order and uses its zero-based index as the key.
- Under reduced motion, all motion stops and the state colors remain.

## Technologies

- All motion is CSS: a completed marker swaps to a check, the connector sweeps to the next marker, and the new active marker pops in after it.
- Source: `packages/tuffex/packages/components/src/steps/`.

<TuffDocSourceLink />