> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/steps.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Steps

Show the progress and current step of a task.


## Basic usage

The current step index starts at `0`. Unless an item has its own `status`, statuses are derived from `current`.


1. Create
1. 2Review
1. 3Done

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/basic.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: 'Create' }, { title: 'Review' }, { title: 'Done' }];

export function StepsBasic() {
  return <Steps aria-label="Task steps" items={items} current={1} />;
}
```

Expand code


## Examples

### Controlled steps

Providing `onChange` makes steps selectable. Store the reported index in application state; the component does not advance it automatically.


1. 1Create
1. 2Review
1. 3Done

Current step: Create

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/controlled.tsx"
import { Flex, Steps, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const items = [{ title: 'Create' }, { title: 'Review' }, { title: 'Done' }];

export function StepsControlled() {
  const [current, setCurrent] = useState(0);
  return (
    <Flex direction="column" gap="md">
      <Steps aria-label="Selectable steps" items={items} current={current} onChange={setCurrent} />
      <Text role="status" tone="muted">
        Current step: {items[current]?.title}
      </Text>
    </Flex>
  );
}
```

Expand code

### Vertical layout

Set `direction="vertical"` to arrange the steps vertically.


1. CreateEnter basic information
1. 2ReviewCheck and confirm settings
1. 3DoneGet started

vertical.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/vertical.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [
  { title: 'Create', description: 'Enter basic information' },
  { title: 'Review', description: 'Check and confirm settings' },
  { title: 'Done', description: 'Get started' },
];

export function StepsVertical() {
  return <Steps aria-label="Vertical steps" direction="vertical" current={1} items={items} />;
}
```

Expand code

### Error state

Use `status="error"` to mark the current step as failed.


1. Create
1. Review
1. 3Done

error.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/error.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: 'Create' }, { title: 'Review' }, { title: 'Done' }];

export function StepsError() {
  return <Steps aria-label="Failed step" current={1} status="error" items={items} />;
}
```

Expand code

### Dot steps

Set `progressDot` to display steps with dot indicators.


1. Create
1. Review
1. Done

capabilities.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/capabilities.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: 'Create' }, { title: 'Review' }, { title: 'Done' }];

export function Capabilities() {
  return <Steps aria-label="Dot steps" progressDot current={1} items={items} />;
}
```

Expand code

### Progress within a step

`percent` shows progress inside the current step icon, not overall task progress. It is not shown in dot mode.


1. Create
1. 2Review65%
1. 3Done

progress.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/steps/progress.tsx"
import { Steps } from '@ifhover/leaf-ui';

const items = [{ title: 'Create' }, { title: 'Review', description: '65%' }, { title: 'Done' }];

export function StepsProgress() {
  return <Steps aria-label="Progress within a step" current={1} percent={65} items={items} />;
}
```

Expand code


## API

### Steps API

Configure the current step, step data and layout.

| Property      | Type                                                                                  | Default        | Description                                                               |
| ------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------- |
| `items`       | `readonly `[`StepItem`](#stepitem)`[]`                                                | Required       | Step items                                                                |
| `current`     | `number`                                                                              | `0`            | Current step index, starting at 0                                         |
| `status`      | `'process' \| 'finish' \| 'error'`                                                    | `'process'`    | Current step status                                                       |
| `direction`   | `'horizontal' \| 'vertical'`                                                          | `'horizontal'` | Layout direction                                                          |
| `size`        | `'sm' \| 'md' \| 'lg'`                                                                | `'md'`         | Step size                                                                 |
| `loading`     | `boolean`                                                                             | `false`        | Show a spinner for the current step                                       |
| `onChange`    | `(current: number) => void`                                                           | —              | Makes steps selectable                                                    |
| `progressDot` | `boolean \| ((dot: ReactNode, info: { index: number; status: string }) => ReactNode)` | —              | Use progress dots, optionally with custom content.                        |
| `percent`     | `number`                                                                              | —              | Progress inside the current step icon (0–100); not displayed in dot mode. |

### StepItem

Describe an individual step title, status and supporting content.

| Property      | Type                                         | Default  | Description              |
| ------------- | -------------------------------------------- | -------- | ------------------------ |
| `key`         | `string`                                     | —        | Stable identifier        |
| `title`       | `ReactNode`                                  | Required | Step title               |
| `description` | `ReactNode`                                  | —        | Supporting description   |
| `icon`        | `ReactNode`                                  | —        | Custom icon              |
| `status`      | `'wait' \| 'process' \| 'finish' \| 'error'` | —        | Override the item status |
| `disabled`    | `boolean`                                    | `false`  | Disable interaction.     |
