Steps

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

Loading...

Anatomy

<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.

Controlled

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

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.

Vertical

Use the orientation prop to display the steps vertically.

API Reference

Props

Root

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
count
number

The total number of steps

defaultStep
number

The initial value of the stepper when rendered. Use when you don't need to control the value of the stepper.

ids
ElementIds

The custom ids for the stepper elements

isStepSkippable() => false
(index: number) => boolean

Whether a step can be skipped during navigation. Skippable steps are bypassed when using next/prev.

isStepValid() => true
(index: number) => boolean

Whether a step is valid. Invalid steps block forward navigation in linear mode.

linear
boolean

If `true`, the stepper requires the user to complete the steps in order

onStepChange
(details: StepChangeDetails) => void

Callback to be called when the value changes

onStepComplete
VoidFunction

Callback to be called when a step is completed

onStepInvalid
(details: StepInvalidDetails) => void

Called when navigation is blocked due to an invalid step.

orientation'horizontal'
'horizontal' | 'vertical'

The orientation of the stepper

step
number

The controlled value of the stepper

AttributeDescription
[data-steps-root]<uid>
[data-orientation]The orientation of the steps
[data-complete]Present when the steps value is complete
CSS VariableDescription
--steps-percentThe steps percent value for the Root

CompletedContent

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[data-steps-content]<uid>
[data-type]"complete"
[data-state]"open" | "closed"
[data-orientation]The orientation of the completedcontent

Content

Renders a <div> element.

PropDefaultType
index
number

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[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

Renders a <span> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[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

Renders a <div> element.

PropDefaultType
index
number

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[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

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[data-steps-list]<uid>
[data-orientation]The orientation of the list

NextTrigger

Renders a <button> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

PrevTrigger

Renders a <button> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Progress

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[data-steps-progress]<uid>
[data-complete]Present when the progress value is complete

RootProvider

Renders a <div> element.

PropDefaultType
value
UseStepsReturn

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Separator

Renders a <div> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[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

Renders a <button> element.

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
AttributeDescription
[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

PropertyType
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