Stepper

The <x-wirekit::stepper> component shows progress through a multi-step flow. Each step is automatically styled based on its position relative to the current step: completed (filled), current (outlined), or upcoming (muted).

Usage

<x-wirekit::stepper :steps="['Cart', 'Shipping', 'Payment', 'Confirm']" :current="2" />

Steps before current show a checkmark. The current step is outlined with the accent color. Upcoming steps are muted.

With Descriptions

<x-wirekit::stepper :steps="[
    ['label' => 'Cart', 'description' => 'Review items'],
    ['label' => 'Shipping', 'description' => 'Address details'],
    ['label' => 'Payment', 'description' => 'Card info'],
    ['label' => 'Confirm', 'description' => 'Final review'],
]" :current="3" />

Vertical Orientation

<x-wirekit::stepper orientation="vertical" :steps="[
    ['label' => 'Account', 'description' => 'Create your account'],
    ['label' => 'Profile', 'description' => 'Tell us about you'],
    ['label' => 'Plan', 'description' => 'Choose a plan'],
]" :current="2" />

Letting the reader step back

A stepper looks like the way back, and a finished step that does not answer a click costs the reader a click and a guess about the state of the page. Give the step a destination and it becomes one:

{{-- 1. `href` renders a real <a>; use `wire:click` instead for a Livewire action. --}}
{{-- 2. Only steps BEFORE `current` become operable — the rest stay presentational. --}}
<x-wirekit::stepper :current="3" :steps="[
    ['label' => 'Details', 'href' => route('wizard.details')],
    ['label' => 'Documents', 'href' => route('wizard.documents')],
    ['label' => 'Review'],
]" />

The first two carry a pointer and a focus ring; the third does not, and neither would a fourth. Hover the finished steps to see the difference:

<x-wirekit::stepper :current="3" :steps="[
    ['label' => 'Details', 'href' => '#', 'description' => 'Done — click to go back'],
    ['label' => 'Documents', 'href' => '#', 'description' => 'Done — click to go back'],
    ['label' => 'Review', 'description' => 'You are here'],
    ['label' => 'Submit', 'href' => '#', 'description' => 'Not offered, even with an href'],
]" />

Props

Accessibility

• Outer <ol aria-label="Progress"> — semantic ordered list
• Current step marked with aria-current="step" on its <li>
• Completed steps include a visually hidden "Completed:" label for screen readers — the word runs through Laravel's __(), so it follows your app locale rather than staying English (see Localization)
• Step numbers and icons are aria-hidden="true" (state conveyed via aria-current)
• Connector lines are aria-hidden="true" (decorative)

Keyboard Interaction

By default the stepper is a presentational progress indicator — a semantic <ol> of steps with no focusable controls of its own. The current position is conveyed with aria-current, and the numbers, icons and connector lines are aria-hidden. Nothing to tab to, nothing to press.

Give a step an href or a wire:click and it becomes a real link or button — but only once it is completed (see "Letting the reader step back" above). A completed step is then an ordinary tab stop with a focus ring, and its accessible name is built from everything the element wraps — which is more than the label. The link covers the circle and the label block, so the name is the visually hidden "Completed:" prefix, then the label, then the description if the step has one. The first step in the preview under "Letting the reader step back" is announced as "Completed: Details Done — click to go back", not as "Details".

That is worth knowing before you write a description on a step you intend to make operable: it is part of that step's name, not a caption sitting beside it. Write it so it reads as one phrase with the label, or leave it off.

If your flow needs the user to move forward between steps, use <x-wirekit::wizard>: it holds the step, gates advancing on a per-step condition, announces the change to a screen reader, and renders this stepper inside itself. The stepper reflects state either way — it does not own the navigation, and the wizard does not change that.

Driving current from your own controls stays perfectly valid and is the right answer when the flow's state already lives somewhere else.

Pitfalls

• A step becomes clickable only when you give it somewhere to go, and only once it is completed. The stepper shows where the reader is; it is not a nav, and it will not invent one. An upcoming step never becomes operable even with an href, because a jump forward is a permission only your flow can grant — a clickable skip in a checkout walks around the validation the steps exist for. <x-wirekit::wizard> keeps the same position for the forward direction: it adds Back and Next around the stepper and gates advancing.

Design Tokens

Customization

Accent Color

The step indicator circles use --color-wk-accent for the current and completed states. Override it to match your brand:

<x-wirekit::stepper :steps="['Cart', 'Shipping', 'Payment', 'Confirm']" :current="3" style="--color-wk-accent: #15803d; --color-wk-accent-fg: #fff; max-width: 32rem; margin-inline: auto;" />

<x-wirekit::stepper :steps="['Cart', 'Shipping', 'Payment', 'Confirm']" :current="2" style="--color-wk-accent: #9333ea; --color-wk-accent-fg: #fff; max-width: 32rem; margin-inline: auto;" />

Completed Step at End

<x-wirekit::stepper :steps="['Cart', 'Shipping', 'Payment', 'Confirm']" :current="5" style="max-width: 32rem; margin-inline: auto;" />

Vertical with Custom Color

<x-wirekit::stepper orientation="vertical" :steps="[
    ['label' => 'Order Placed', 'description' => 'April 1, 2026'],
    ['label' => 'Processing', 'description' => 'April 2, 2026'],
    ['label' => 'Shipped', 'description' => 'Estimated April 5'],
    ['label' => 'Delivered', 'description' => 'Pending'],
]" :current="3" style="--color-wk-accent: #2563eb; --color-wk-accent-fg: #fff; max-width: 32rem; margin-inline: auto;" />

Token Map by Element

To change the circle size globally, use scoped personalization:

// config/wirekit.php
'personalizations' => [
    'stepper' => [
        'my-scope' => [
            'circle' => 'w-10 h-10 text-base', // larger circles
        ],
    ],
],

<x-wirekit::stepper scope="my-scope" :steps="['A', 'B', 'C']" :current="2" />

Config Defaults

The defaults live in config/wirekit.php under components.stepper. Override them globally:

'components' => [
    'stepper' => ['orientation' => 'vertical'], // default to vertical
],

Further Reading

• MDN: aria-current — used with value "step" to mark the active step
• MDN: <ol> element — semantic ordered list
• WAI-ARIA: step indicator patterns