Steps
Used to guide users through a series of steps in a process
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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. | |
count | numberThe total number of steps | |
defaultStep | numberThe initial value of the stepper when rendered. Use when you don't need to control the value of the stepper. | |
ids | ElementIdsThe custom ids for the stepper elements | |
isStepSkippable | () => false | (index: number) => booleanWhether a step can be skipped during navigation. Skippable steps are bypassed when using next/prev. |
isStepValid | () => true | (index: number) => booleanWhether a step is valid. Invalid steps block forward navigation in linear mode. |
linear | booleanIf `true`, the stepper requires the user to complete the steps in order | |
onStepChange | (details: StepChangeDetails) => voidCallback to be called when the value changes | |
onStepComplete | VoidFunctionCallback to be called when a step is completed | |
onStepInvalid | (details: StepInvalidDetails) => voidCalled when navigation is blocked due to an invalid step. | |
orientation | 'horizontal' | 'horizontal' | 'vertical'The orientation of the stepper |
step | numberThe controlled value of the stepper |
| Attribute | Description |
|---|---|
[data-steps-root] | <uid> |
[data-orientation] | The orientation of the steps |
[data-complete] | Present when the steps value is complete |
| CSS Variable | Description |
|---|---|
--steps-percent | The steps percent value for the Root |
CompletedContent
Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[data-steps-content] | <uid> |
[data-type] | "complete" |
[data-state] | "open" | "closed" |
[data-orientation] | The orientation of the completedcontent |
Content
Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
index | number | |
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[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.
| Prop | Default | Type |
|---|---|---|
index | number | |
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[data-steps-list] | <uid> |
[data-orientation] | The orientation of the list |
NextTrigger
Renders a <button> element.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse 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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse 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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[data-steps-progress] | <uid> |
[data-complete] | Present when the progress value is complete |
RootProvider
Renders a <div> element.
| Prop | Default | Type |
|---|---|---|
value | UseStepsReturn | |
asChild | booleanUse 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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[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.
| Prop | Default | Type |
|---|---|---|
asChild | booleanUse the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide. |
| Attribute | Description |
|---|---|
[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 |
|---|---|
items | V[]The steps in the flow, excluding disabled ones |
value | string | nullThe value of the current step, `COMPLETE` past the last step, or `null` when there are no steps |
index | numberThe position of the current step in the flow |
item | V | nullThe current step item |
count | numberThe number of steps in the flow, excluding disabled ones |
percent | numberThe percentage of the stepper |
complete | booleanWhether the stepper has moved past the last step |
completedValues | string[]The values of the completed steps |
hasNextStep | booleanWhether the stepper has a next step |
hasPreviousStep | booleanWhether the stepper has a previous step |
canSkip | booleanWhether the current step is optional and can be skipped |
canComplete | booleanWhether `goToNextStep` would complete the stepper |
getItemState | (props: ItemProps) => ItemStateReturns the state of the item with the given value |
setValue | (value: string) => voidFunction to set the value of the stepper |
goToNextStep | VoidFunctionFunction to go to the next step |
goToPreviousStep | VoidFunctionFunction to go to the previous step |
skipStep | VoidFunctionFunction to skip the current step. Only works when the step is optional. |
resetStep | VoidFunctionFunction to reset the stepper to its initial state |
setCompletedValues | (values: string[]) => voidFunction to set the completed steps |
getRootState | () => RootStateReturns the state of the root |
getCompletedContentProps | () => T["element"]Returns the props for the content shown once the flow is complete |