Stepperize v9Explore the changes
Skip to Content
Stepperize

Styling

Style the primitives through data attributes.

The primitives ship no styles. Each one exposes its state as data-* attributes, and you style against them with Tailwind variants, plain CSS, or anything that can target an attribute selector. Your markup stays yours; the library tells you what state each element is in.

Attributes

AttributeSet onValues
data-componentEvery primitivestepper, stepper-list, stepper-item, stepper-trigger, stepper-title, stepper-description, stepper-indicator, stepper-content, stepper-prev, stepper-next
data-stateItem, Trigger, Indicatorpending, current, complete
data-invalidItem, Trigger, IndicatorPresent after a rejected next() or validate(), until the step's data changes
data-disabledItem, Trigger, Prev, NextPresent when the action is not available
data-pendingRoot, Prev, NextPresent while an async schema, guard or onFinish runs
data-finishedRootPresent once the flow has finished, until it changes
data-orientationRoot, Listhorizontal, vertical
data-stepItem, Trigger, ContentThe step id

data-state: the workhorse

data-state is the state of the step:

  • current: the step being shown.
  • complete: next() validated it and moved on, and its data has not changed since.
  • pending: everything else.

With Tailwind

Target it with the data-[…] variant. A typical trigger and indicator:

<Stepper.Trigger className="flex items-center gap-2 text-muted-foreground data-[state=current]:text-foreground data-disabled:opacity-50">
  <Stepper.Indicator className="size-6 rounded-full border data-[state=complete]:bg-primary data-invalid:border-destructive" />
  <Stepper.Title />
</Stepper.Trigger>

Styling children with group-data

Put group on the element that has the attribute, then read it from a child with group-data-[state=…]. This is how the blocks swap a number for a check mark once a step is complete, with no JavaScript:

<Stepper.List>
  {(step, index) => (
    <Stepper.Item>
      <Stepper.Indicator className="group grid size-7 place-items-center rounded-full border">
        <span className="group-data-[state=complete]:hidden">{index + 1}</span>
        <CheckIcon className="hidden size-4 group-data-[state=complete]:block" />
      </Stepper.Indicator>
    </Stepper.Item>
  )}
</Stepper.List>

When several elements each have their own data-state, name the group (group/item and group-data-[state=current]/item:) so a child reads the right one.

With plain CSS

Attribute selectors work anywhere:

[data-component="stepper-list"] {
  display: flex;
  gap: 1rem;
}
[data-component="stepper-list"][data-orientation="vertical"] {
  flex-direction: column;
}
[data-component="stepper-indicator"][data-state="complete"] {
  background: var(--primary);
}
[data-component="stepper-next"][data-pending] {
  cursor: progress;
}

Here it is on a real block. Each indicator becomes a check mark when its step is complete:

Step 1 of 4

Profile

Tell us about you

Put the profile fields here. The rail stays fixed while this column scrolls independently on long forms.

data-invalid

Present on the item, trigger and indicator of a step whose last next() was rejected by its schema, until that step's data changes.

<Stepper.Indicator className="border data-invalid:border-destructive data-invalid:text-destructive" />

data-orientation

orientation on Stepper.Root is reflected on the root and the list, and decides which arrow keys move between tabs. Style both layouts from one definition:

<Stepper.Root orientation="vertical" className="data-[orientation=vertical]:flex data-[orientation=vertical]:gap-8">
  <Stepper.List className="flex gap-2 data-[orientation=vertical]:flex-col">
    {/* items */}
  </Stepper.List>
</Stepper.Root>

data-component

Every primitive carries a data-component value: a stable selector that survives class name changes, useful for design-system overrides.

Disabled and pending

A button that cannot be used right now gets data-disabled. Style that attribute rather than :disabled: while an async check runs, the buttons are aria-disabled instead of disabled, so the one that was pressed keeps keyboard focus.

Lines between steps

There is no separator component. Draw the line with CSS on the items, which keeps the list a clean list of steps for screen readers.

[data-component="stepper-item"]:not(:last-child)::after {
  content: "";
  flex: 1;
  height: 1px;
  background: var(--border);
}
[data-component="stepper-item"][data-state="complete"]::after {
  background: var(--primary);
}

State is not position

data-state="complete" means the step was validated, not that it is before the current one. A step that was skipped is pending even if it is earlier in the list. To style by position instead, see Step state.

Where to go next

Edit on GitHub

Last updated on

On this page