# Steps

URL: https://ark-ui.com/docs/components/steps
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/steps.mdx

Used to guide users through a series of steps in a process

---

<ComponentPreview id="Steps" />

## Usage

The `Steps` component is used to guide users through a series of steps in a process.

- Supports horizontal and vertical orientations.
- Support for changing the active step with the keyboard and pointer.
- Support for linear and non-linear steps.

```jsx
import { Steps } from '@ark-ui/react/steps'
```

## Examples

### Basic

Here's a basic example of the `Steps` component.

<Example component="steps" id="basic" />

### Controlled Steps

Using the `RootProvider` component, you can control the active step by using the `step` prop and handling the
`onStepChange` event.

<Example id="controlled" />

### Root Provider

An alternative way to control the steps is to use the `RootProvider` component and the `useSteps` store hook.

This way you can access the steps state and methods from outside the steps.

<Example id="root-provider" />

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

### Props

**Component API Reference**

#### React

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | The total number of steps |
| `defaultStep` | `number` | No | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| `ids` | `ElementIds` | No | The custom ids for the stepper elements |
| `linear` | `boolean` | No | If `true`, the stepper requires the user to complete the steps in order |
| `onStepChange` | `(details: StepChangeDetails) => void` | No | Callback to be called when the value changes |
| `onStepComplete` | `VoidFunction` | No | Callback to be called when a step is completed |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the stepper |
| `step` | `number` | No | The controlled value of the stepper |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the steps |


**CompletedContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | indicator |
| `[data-complete]` | Present when the indicator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | item |
| `[data-orientation]` | The orientation of the item |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | list |
| `[data-orientation]` | The orientation of the list |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | progress |
| `[data-complete]` | Present when the progress value is complete |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseStepsReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | separator |
| `[data-orientation]` | The orientation of the separator |
| `[data-complete]` | Present when the separator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the trigger |
| `[data-complete]` | Present when the trigger value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


#### Solid

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | The total number of steps |
| `defaultStep` | `number` | No | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| `ids` | `ElementIds` | No | The custom ids for the stepper elements |
| `linear` | `boolean` | No | If `true`, the stepper requires the user to complete the steps in order |
| `onStepChange` | `(details: StepChangeDetails) => void` | No | Callback to be called when the value changes |
| `onStepComplete` | `VoidFunction` | No | Callback to be called when a step is completed |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the stepper |
| `step` | `number` | No | The controlled value of the stepper |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the steps |


**CompletedContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | indicator |
| `[data-complete]` | Present when the indicator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | item |
| `[data-orientation]` | The orientation of the item |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | list |
| `[data-orientation]` | The orientation of the list |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | progress |
| `[data-complete]` | Present when the progress value is complete |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseStepsReturn` | Yes |  |
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'div'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | separator |
| `[data-orientation]` | The orientation of the separator |
| `[data-complete]` | Present when the separator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `(props: ParentProps<'button'>) => Element` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the trigger |
| `[data-complete]` | Present when the trigger value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


#### Vue

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | The total number of steps |
| `defaultStep` | `number` | No | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `ElementIds` | No | The custom ids for the stepper elements |
| `linear` | `boolean` | No | If `true`, the stepper requires the user to complete the steps in order |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the stepper |
| `step` | `number` | No | The controlled value of the stepper |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the steps |


**CompletedContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the content |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | indicator |
| `[data-complete]` | Present when the indicator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | item |
| `[data-orientation]` | The orientation of the item |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | list |
| `[data-orientation]` | The orientation of the list |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Progress Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | progress |
| `[data-complete]` | Present when the progress value is complete |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `StepsApi<PropTypes>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Separator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | separator |
| `[data-orientation]` | The orientation of the separator |
| `[data-complete]` | Present when the separator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the trigger |
| `[data-complete]` | Present when the trigger value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


#### Svelte

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | The total number of steps |
| `defaultStep` | `number` | No | The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `ElementIds` | No | The custom ids for the stepper elements |
| `linear` | `boolean` | No | If `true`, the stepper requires the user to complete the steps in order |
| `onStepChange` | `(details: StepChangeDetails) => void` | No | Callback to be called when the value changes |
| `onStepComplete` | `VoidFunction` | No | Callback to be called when a step is completed |
| `orientation` | `'horizontal' | 'vertical'` | No | The orientation of the stepper |
| `ref` | `Element` | No |  |
| `step` | `number` | No | The controlled value of the stepper |


**Root Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | root |
| `[data-orientation]` | The orientation of the steps |


**CompletedContent Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the content |


**Context Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseStepsContext]>` | Yes |  |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | indicator |
| `[data-complete]` | Present when the indicator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**ItemContext Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `render` | `Snippet<[UseStepsItemContext]>` | Yes |  |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | item |
| `[data-orientation]` | The orientation of the item |


**List Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'ol'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**List Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | list |
| `[data-orientation]` | The orientation of the list |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Progress Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Progress Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | progress |
| `[data-complete]` | Present when the progress value is complete |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseStepsReturn` | Yes |  |
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Separator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'div'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Separator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | separator |
| `[data-orientation]` | The orientation of the separator |
| `[data-complete]` | Present when the separator value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `Snippet<[PropsFn<'button'>]>` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `ref` | `Element` | No |  |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | steps |
| `[data-part]` | trigger |
| `[data-state]` | "open" | "closed" |
| `[data-orientation]` | The orientation of the trigger |
| `[data-complete]` | Present when the trigger value is complete |
| `[data-current]` | Present when current |
| `[data-incomplete]` |  |


### Context

These are the properties available when using `Steps.Context`, `useStepsContext` hook or `useSteps` hook.

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `value` | `number` | The value of the stepper. |
| `percent` | `number` | The percentage of the stepper. |
| `count` | `number` | The total number of steps. |
| `hasNextStep` | `boolean` | Whether the stepper has a next step. |
| `hasPrevStep` | `boolean` | Whether the stepper has a previous step. |
| `isCompleted` | `boolean` | Whether the stepper is completed. |
| `setStep` | `(step: number) => void` | Function to set the value of the stepper. |
| `goToNextStep` | `VoidFunction` | Function to go to the next step. |
| `goToPrevStep` | `VoidFunction` | Function to go to the previous step. |
| `resetStep` | `VoidFunction` | Function to go to reset the stepper. |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the item at the given index. |
