# Steps

URL: https://ark-ui.com/docs/react/components/steps
LLM: https://ark-ui.com/llms.txt/components/steps

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

---

---
id: steps
title: Steps
description: Used to guide users through a series of steps in a process
---



## Anatomy



```tsx
<Steps.Root>
  <Steps.List>
    <Steps.Item>
      <Steps.Trigger>
        <Steps.Indicator />
      </Steps.Trigger>
      <Steps.Separator />
    </Steps.Item>
  </Steps.List>
  <Steps.Content />
  <Steps.CompletedContent />
  <Steps.PrevTrigger />
  <Steps.NextTrigger />
</Steps.Root>
```

## Examples

### Basic

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

```tsx
import { Steps } from '@ark-ui/react/steps'
import button from 'styles/button.module.css'
import styles from 'styles/steps.module.css'

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
]

export const Basic = () => {
  return (
    <Steps.Root className={styles.Root} items={items}>
      <Steps.List className={styles.List}>
        {items.map((item, index) => (
          <Steps.Item className={styles.Item} key={item.value} value={item.value}>
            <Steps.Trigger className={styles.Trigger}>
              <Steps.Indicator className={styles.Indicator}>{index + 1}</Steps.Indicator>
              <span>{item.title}</span>
            </Steps.Trigger>
            <Steps.Separator className={styles.Separator} />
          </Steps.Item>
        ))}
      </Steps.List>

      {items.map((item) => (
        <Steps.Content className={styles.Content} key={item.value} value={item.value}>
          {item.title} - {item.description}
        </Steps.Content>
      ))}

      <Steps.CompletedContent className={styles.CompletedContent}>
        Steps Complete - Thank you for filling out the form!
      </Steps.CompletedContent>

      <div className={styles.Actions}>
        <Steps.PrevTrigger className={button.Root}>Back</Steps.PrevTrigger>
        <Steps.NextTrigger className={button.Root} data-variant="solid">
          Next
        </Steps.NextTrigger>
      </div>
    </Steps.Root>
  )
}
```

### Controlled

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

```tsx
import { Steps } from '@ark-ui/react/steps'
import { useState } from 'react'
import button from 'styles/button.module.css'
import styles from 'styles/steps.module.css'

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
]

export const Controlled = () => {
  const [value, setValue] = useState<string | null>('first')

  return (
    <div className="stack">
      <output>current step: {value}</output>

      <Steps.Root
        className={styles.Root}
        items={items}
        value={value ?? undefined}
        onValueChange={(details) => setValue(details.value)}
      >
        <Steps.List className={styles.List}>
          {items.map((item, index) => (
            <Steps.Item className={styles.Item} key={item.value} value={item.value}>
              <Steps.Trigger className={styles.Trigger}>
                <Steps.Indicator className={styles.Indicator}>{index + 1}</Steps.Indicator>
                <span>{item.title}</span>
              </Steps.Trigger>
              <Steps.Separator className={styles.Separator} />
            </Steps.Item>
          ))}
        </Steps.List>

        {items.map((item) => (
          <Steps.Content className={styles.Content} key={item.value} value={item.value}>
            {item.title} - {item.description}
          </Steps.Content>
        ))}

        <Steps.CompletedContent className={styles.CompletedContent}>
          Steps Complete - Thank you for filling out the form!
        </Steps.CompletedContent>

        <div className={styles.Actions}>
          <Steps.PrevTrigger className={button.Root}>Back</Steps.PrevTrigger>
          <Steps.NextTrigger className={button.Root} data-variant="solid">
            Next
          </Steps.NextTrigger>
        </div>
      </Steps.Root>
    </div>
  )
}
```

### Root Provider

An alternative way to control the steps is to use the `RootProvider` component and the `useSteps` hook. This way you can
access the state and methods from outside the component.

```tsx
import { Steps, useSteps } from '@ark-ui/react/steps'
import button from 'styles/button.module.css'
import styles from 'styles/steps.module.css'

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
]

export const RootProvider = () => {
  const steps = useSteps({ items })

  return (
    <div className="stack">
      <output>current step: {steps.index + 1}</output>

      <Steps.RootProvider className={styles.Root} value={steps}>
        <Steps.List className={styles.List}>
          {items.map((item, index) => (
            <Steps.Item className={styles.Item} key={item.value} value={item.value}>
              <Steps.Trigger className={styles.Trigger}>
                <Steps.Indicator className={styles.Indicator}>{index + 1}</Steps.Indicator>
                <span>{item.title}</span>
              </Steps.Trigger>
              <Steps.Separator className={styles.Separator} />
            </Steps.Item>
          ))}
        </Steps.List>

        {items.map((item) => (
          <Steps.Content className={styles.Content} key={item.value} value={item.value}>
            {item.title} - {item.description}
          </Steps.Content>
        ))}

        <Steps.CompletedContent className={styles.CompletedContent}>
          Steps Complete - Thank you for filling out the form!
        </Steps.CompletedContent>

        <div className={styles.Actions}>
          <Steps.PrevTrigger className={button.Root}>Back</Steps.PrevTrigger>
          <Steps.NextTrigger className={button.Root} data-variant="solid">
            Next
          </Steps.NextTrigger>
        </div>
      </Steps.RootProvider>
    </div>
  )
}
```

### Vertical

Use the `orientation` prop to display the steps vertically.

```tsx
import { Steps } from '@ark-ui/react/steps'
import button from 'styles/button.module.css'
import styles from 'styles/steps.module.css'

const items = [
  { value: 'first', title: 'First', description: 'Contact Info' },
  { value: 'second', title: 'Second', description: 'Date & Time' },
  { value: 'third', title: 'Third', description: 'Select Rooms' },
]

export const Vertical = () => {
  return (
    <Steps.Root className={styles.Root} items={items} orientation="vertical">
      <Steps.List className={styles.List}>
        {items.map((item, index) => (
          <Steps.Item className={styles.Item} key={item.value} value={item.value}>
            <Steps.Trigger className={styles.Trigger}>
              <Steps.Indicator className={styles.Indicator}>{index + 1}</Steps.Indicator>
              <span>{item.title}</span>
            </Steps.Trigger>
            <Steps.Separator className={styles.Separator} />
          </Steps.Item>
        ))}
      </Steps.List>

      {items.map((item) => (
        <Steps.Content className={styles.Content} key={item.value} value={item.value}>
          <div className="vstack">
            <span>
              {item.title} - {item.description}
            </span>
            <div className={styles.Actions}>
              <Steps.PrevTrigger className={button.Root}>Back</Steps.PrevTrigger>
              <Steps.NextTrigger className={button.Root} data-variant="solid">
                Next
              </Steps.NextTrigger>
            </div>
          </div>
        </Steps.Content>
      ))}

      <Steps.CompletedContent className={styles.CompletedContent}>
        <div className="vstack">
          <span>Steps Complete - Thank you for filling out the form!</span>
          <Steps.PrevTrigger className={button.Root}>Back</Steps.PrevTrigger>
        </div>
      </Steps.CompletedContent>
    </Steps.Root>
  )
}
```

## API Reference

### Props

### Root

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

**`count`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The total number of steps

**`defaultStep`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The initial value of the stepper when rendered.
Use when you don't need to control the value of the stepper.

**`ids`**
Type: `ElementIds`
Required: false
Default Value: `undefined`
Description: The custom ids for the stepper elements

**`isStepSkippable`**
Type: `(index: number) => boolean`
Required: false
Default Value: `() => false`
Description: Whether a step can be skipped during navigation.
Skippable steps are bypassed when using next/prev.

**`isStepValid`**
Type: `(index: number) => boolean`
Required: false
Default Value: `() => true`
Description: Whether a step is valid. Invalid steps block forward navigation in linear mode.

**`linear`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: If `true`, the stepper requires the user to complete the steps in order

**`onStepChange`**
Type: `(details: StepChangeDetails) => void`
Required: false
Default Value: `undefined`
Description: Callback to be called when the value changes

**`onStepComplete`**
Type: `VoidFunction`
Required: false
Default Value: `undefined`
Description: Callback to be called when a step is completed

**`onStepInvalid`**
Type: `(details: StepInvalidDetails) => void`
Required: false
Default Value: `undefined`
Description: Called when navigation is blocked due to an invalid step.

**`orientation`**
Type: `'horizontal' | 'vertical'`
Required: false
Default Value: `"horizontal"`
Description: The orientation of the stepper

**`step`**
Type: `number`
Required: false
Default Value: `undefined`
Description: The controlled value of the stepper

#### Data Attributes

**`data-steps-root`**: <uid>
**`data-orientation`**: The orientation of the steps
**`data-complete`**: Present when the steps value is complete

### CompletedContent

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-content`**: <uid>
**`data-type`**: "complete"
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the completedcontent

### Content

#### Props

**`index`**
Type: `number`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-content`**: <uid>
**`data-value`**: The value of the item
**`data-type`**: "step"
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the content
**`data-complete`**: Present when the content value is complete

### Indicator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-indicator`**: <uid>
**`data-orientation`**: The orientation of the indicator
**`data-value`**: The value of the item
**`data-complete`**: Present when the indicator value is complete
**`data-current`**: Present when current
**`data-incomplete`**: Present when incomplete
**`data-skipped`**: Present when the flow moved past it without completing it
**`data-invalid`**: Present when invalid
**`data-optional`**: Present when optional
**`data-locked`**: Present when completed and it cannot be returned to
**`data-disabled`**: Present when disabled

### Item

#### Props

**`index`**
Type: `number`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-item`**: <uid>
**`data-orientation`**: The orientation of the item
**`data-value`**: The value of the item
**`data-complete`**: Present when the item value is complete
**`data-current`**: Present when current
**`data-incomplete`**: Present when incomplete
**`data-skipped`**: Present when the flow moved past it without completing it
**`data-invalid`**: Present when invalid
**`data-optional`**: Present when optional
**`data-locked`**: Present when completed and it cannot be returned to
**`data-disabled`**: Present when disabled

### List

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-list`**: <uid>
**`data-orientation`**: The orientation of the list

### NextTrigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### PrevTrigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Progress

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-progress`**: <uid>
**`data-complete`**: Present when the progress value is complete

### RootProvider

#### Props

**`value`**
Type: `UseStepsReturn`
Required: true
Default Value: `undefined`
Description: undefined

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

### Separator

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-separator`**: <uid>
**`data-orientation`**: The orientation of the separator
**`data-value`**: The value of the item
**`data-complete`**: Present when the separator value is complete
**`data-current`**: Present when current
**`data-incomplete`**: Present when incomplete
**`data-skipped`**: Present when the flow moved past it without completing it
**`data-invalid`**: Present when invalid
**`data-optional`**: Present when optional
**`data-locked`**: Present when completed and it cannot be returned to
**`data-disabled`**: Present when disabled

### Trigger

#### Props

**`asChild`**
Type: `boolean`
Required: false
Default Value: `undefined`
Description: Use the provided child element as the default rendered element, combining their props and behavior.

#### Data Attributes

**`data-steps-trigger`**: <uid>
**`data-state`**: "open" | "closed"
**`data-orientation`**: The orientation of the trigger
**`data-value`**: The value of the item
**`data-complete`**: Present when the trigger value is complete
**`data-current`**: Present when current
**`data-incomplete`**: Present when incomplete
**`data-skipped`**: Present when the flow moved past it without completing it
**`data-invalid`**: Present when invalid
**`data-optional`**: Present when optional
**`data-locked`**: Present when completed and it cannot be returned to
**`data-disabled`**: Present when disabled

### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `items` | `V[]` | The steps in the flow, excluding disabled ones |
| `value` | `string | null` | The value of the current step, `COMPLETE` past the last step, or `null` when there are no steps |
| `index` | `number` | The position of the current step in the flow |
| `item` | `V | null` | The current step item |
| `count` | `number` | The number of steps in the flow, excluding disabled ones |
| `percent` | `number` | The percentage of the stepper |
| `complete` | `boolean` | Whether the stepper has moved past the last step |
| `completedValues` | `string[]` | The values of the completed steps |
| `hasNextStep` | `boolean` | Whether the stepper has a next step |
| `hasPreviousStep` | `boolean` | Whether the stepper has a previous step |
| `canSkip` | `boolean` | Whether the current step is optional and can be skipped |
| `canComplete` | `boolean` | Whether `goToNextStep` would complete the stepper |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state of the item with the given value |
| `setValue` | `(value: string) => void` | Function to set the value of the stepper |
| `goToNextStep` | `VoidFunction` | Function to go to the next step |
| `goToPreviousStep` | `VoidFunction` | Function to go to the previous step |
| `skipStep` | `VoidFunction` | Function to skip the current step. Only works when the step is optional. |
| `resetStep` | `VoidFunction` | Function to reset the stepper to its initial state |
| `setCompletedValues` | `(values: string[]) => void` | Function to set the completed steps |
| `getRootState` | `() => RootState` | Returns the state of the root |
| `getCompletedContentProps` | `() => T["element"]` | Returns the props for the content shown once the flow is complete |

