---
title: "Stepper"
description: "Progress through a fixed sequence of steps, horizontal or stacked."
---

Use it when a task has a known number of stages in a fixed order and the reader benefits from seeing how far along they are: creating an app, onboarding a server, a setup wizard. It shows progress and does not navigate; put Back and Next buttons beside it, as the example does.

_Live example of Stepper — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add stepper
```

Files written — React: components/ui/stepper.tsx. Vue: components/ui/stepper/Stepper.vue, components/ui/stepper/index.ts.

## Usage

React:

```tsx
import { Stepper } from "@/components/ui/stepper"
```

Vue:

```ts
import { Stepper } from "@/components/ui/stepper"
```

## API reference

**`Stepper`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `{ title: string; description?: string }[]` | — | The stages, in order. |
| `value` | `number` | — | Index of the step in progress. Every step before it is complete, and a value equal to `steps.length` marks them all complete. |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | `vertical` stacks the steps with the marker beside the text, for a narrow column. |
| `completedLabel` | `string` | `"completed"` | Read by a screen reader after the title of a finished step. |

Three to five steps fit a horizontal stepper. Past that, or in a sidebar, use `orientation="vertical"`.

## Accessibility

The steps are an ordered list, so their count and order are announced. The step in progress carries `aria-current="step"`, and a finished step's title is followed by the hidden word from `completedLabel`. State is never carried by colour alone: a finished step shows a check where its number was, and the current one has a filled outline.

`completedLabel` defaults to `completed`. [Translating labels](/docs/translating-labels) lists every English default.

## Tokens

Stepper reads its colours, radii and motion from the `--newt-*` tokens. Override a token rather than editing the component.
