Stepperize v9Explore the changes
Skip to Content
Stepperize

Primitives

Props of every Stepper component.

All primitives accept the props of the element they render, a ref, and render to use your own element. See Styling for their data attributes.

Root

Renders a div. Creates the flow and provides it.

PropTypeDescription
Every optionlinear, next, guard, snapshot, step, onChange, onFinish, onInvalidStep.
orientation"horizontal" | "vertical"Default "horizontal".
childrenReactNode | (stepper) => ReactNodeThe function form re-renders on every change.

onChange is the flow's callback, not the DOM event.

The element has role="group" and the name "Stepper"; pass aria-label or aria-labelledby to describe your flow. While an async check or onFinish runs it has aria-busy and data-pending; once the flow has finished it has data-finished.

List

Renders an ol.

PropTypeDescription
childrenReactNode | (step, index) => ReactNodeThe function is called once per step; items inside it need no step prop.
orientation"horizontal" | "vertical"Defaults to the root's.

Item

Renders an li.

PropTypeDescription
stepStep idRequired outside a List function.

Trigger

Renders a button that calls goTo for its step. Must be inside an Item, and should be inside a List.

It is disabled when linear does not allow reaching the step. In a flow that is not linear it is a tab; in a linear flow it is a plain button, with aria-current="step" on the current one.

Title and Description

Render a span with the step's title or description field. Children replace it.

Indicator

Renders a span with aria-hidden. Empty by default: style it, or pass children.

Content

Renders a div while its step is current. It is the tabpanel of its trigger in a flow rendered as tabs, and otherwise a group named after the step's title.

PropTypeDescription
stepStep idRequired.
forceMountbooleanKeep it mounted and hidden while its step is not current.

Prev and Next

Render a button.

  • Next calls next() with no argument, which validates the data stored for the current step. On the last step it finishes the flow; it is never disabled for being at the end.
  • Prev calls prev(), and is disabled when there is nowhere to go back to.

While an async check or onFinish runs, both are aria-disabled and ignore clicks, and have data-pending.

Once the flow has finished, Next is aria-disabled with data-disabled and ignores clicks, so the flow is not submitted twice. It becomes available again when the flow changes. Root has data-finished meanwhile.

Call event.preventDefault() in onClick to handle the move yourself, for example to pass form values:

<Stepper.Next
  onClick={(event) => {
    event.preventDefault();
    stepper.next(form.getValues());
  }}
>
  Continue
</Stepper.Next>

useItem

Stepper.useItem() returns the enclosing item.

FieldTypeDescription
stepStepThe step, with all its fields.
indexnumberIts position.
state"pending" | "current" | "complete"
invalidbooleanIts last validation failed and its data has not changed since.
disabledbooleangoTo would be refused right now.
pendingbooleanA move is running. Every step is disabled meanwhile.

Outside an Item it throws SZ101.

Edit on GitHub

Last updated on

On this page