<x-widget.stepper>
Stepper Blade component for Laravel and Livewire
Step indicator for multi-step flows like checkout and onboarding: bars, dots, chevrons, or labelled steps (across or stacked with descriptions) that can link back, be locked, optional or need attention. Works inside Livewire components: it follows the current step through renders.
php artisan bladewell:add stepper
- Also adds
- Icon
- Works with
- Laravel 12 and 13, Livewire 3 and 4, Tailwind CSS 4.1+, PHP 8.3+
- Guide
- Livewire multi-step form with validation per step
Usage
Livewire
A wizard in one Livewire component: pass the current step from a property and the stepper follows it on every render, the dots and bars too. A step's href is a link, so in a single-page wizard leave it out and give the step buttons of your own their wire:click.
<div class="space-y-6">
<x-widget.stepper.labelled label="Checkout" :current="$step" :steps="['Cart', 'Address', 'Payment', 'Review']" />
{{-- the current step's fields --}}
<div class="flex justify-between">
<x-widget.button variant="neutral" wire:click="back" :disabled="$step === 1">Back</x-widget.button>
<x-widget.button wire:click="next">Continue</x-widget.button>
</div>
</div>
Examples
Bars
One bar per step. Pass a count with :total, or the step names with :steps to show where the user is.
Show code Hide code
<div class="flex w-full max-w-md flex-col gap-6">
<x-widget.stepper :total="4" :current="2" label="Verification" />
<x-widget.stepper :steps="['Cart', 'Shipping', 'Payment', 'Review']" :current="2" label="Checkout" show-label show-steps />
<x-widget.stepper :total="5" :current="4" label="Profile setup" show-label />
</div>
Labelled
Steps are labels, or arrays with a label plus href (links back to done steps) or locked.
- Account, completed
- Verify identity, completed
-
Bank details, current step
-
Go live, locked
Show code Hide code
<x-widget.stepper.labelled label="Onboarding" :current="3" :steps="[
['label' => 'Account', 'href' => '#account'],
['label' => 'Verify identity', 'href' => '#verify'],
'Bank details',
['label' => 'Go live', 'locked' => true],
]" />
States
A step can need attention (error, and an href lets the user go back and fix it), be optional, or be locked until earlier steps are done. On phones only the current step's name shows, so longer flows still fit.
- Account, completed
- Verify identity, needs attention
-
Bank details, current step
-
Invite team, not started Optional
-
Go live, locked
Show code Hide code
<x-widget.stepper.labelled label="Onboarding" :current="3" :steps="[
['label' => 'Account', 'href' => '#account'],
['label' => 'Verify identity', 'error' => true, 'href' => '#verify'],
'Bank details',
['label' => 'Invite team', 'optional' => true],
['label' => 'Go live', 'locked' => true],
]" />
Vertical
orientation="vertical" stacks the steps with a description under each: onboarding checklists, order tracking. It fits phones as it is.
- Order placed, completed We have your order and payment.
-
Packed, completed Your items are boxed and labelled.
-
Shipped, current step On its way with the courier. Tracking arrives by email.
-
Delivered, not started Usually 2 to 4 working days after shipping.
Show code Hide code
<x-widget.stepper.labelled class="max-w-sm" orientation="vertical" label="Order status" :current="3" :steps="[
['label' => 'Order placed', 'description' => 'We have your order and payment.', 'href' => '#order-placed'],
['label' => 'Packed', 'description' => 'Your items are boxed and labelled.'],
['label' => 'Shipped', 'description' => 'On its way with the courier. Tracking arrives by email.'],
['label' => 'Delivered', 'description' => 'Usually 2 to 4 working days after shipping.'],
]" />
Dots
Small dots for short wizards and carousels; the current step stretches into a pill.
Show code Hide code
<div class="flex flex-col items-center gap-6">
<x-widget.stepper.dots :total="4" :current="2" label="Welcome tour" />
<x-widget.stepper.dots :total="6" :current="5" label="Photo" />
</div>
Chevrons
Arrow-shaped segments in a row, like a checkout breadcrumb. Completed steps can link back; on phones the other steps shrink to their number.
- Cart , completed
- Shipping , completed
-
Payment , current step
-
Review , not started
Show code Hide code
<x-widget.stepper.chevrons label="Checkout" :current="3" :steps="[
['label' => 'Cart', 'href' => '#cart'],
['label' => 'Shipping', 'href' => '#shipping'],
'Payment',
'Review',
]" />
Props
Other attributes, such as autocomplete or data-*, are passed through to the element. class styles the component's outer wrapper.
<x-widget.stepper>
| Prop | Default | Description |
|---|---|---|
| total |
null
|
A count of steps, or their names with :steps (then total can be left out). |
| steps |
[]
|
The steps' names: ['Cart', 'Shipping', 'Payment'], or the other steppers' arrays (only 'label' is used here). |
| current |
1
|
The step you're on, counting from 1; kept between the first and the last. |
| label |
null
|
The bar's name for screen readers (Progress when left out), said before "Step 2 of 4". With show-label, shown when the current step has no name. |
| show-label |
false
|
A line above the bars: the current step's name (or the label) and "Step 2 of 4". |
| show-steps |
false
|
Step names under the bars from the sm breakpoint up; on phones they'd crowd each other. |
<x-widget.stepper.chevrons>
| Prop | Default | Description |
|---|---|---|
| steps |
[]
|
Labels, or arrays: ['label' => 'Shipping', 'href' => …]. href makes a done step a link back to it. |
| current |
1
|
The step you're on, counting from 1; kept between the first and the last. |
| label |
'Progress'
|
The steps' name for screen readers. |
<x-widget.stepper.dots>
| Prop | Default | Description |
|---|---|---|
| total | Required | Required: how many steps there are. |
| current |
1
|
The step you're on, counting from 1; kept between the first and the last. |
| label |
null
|
The dots' name for screen readers (Progress when left out), said before "Step 2 of 4". |
<x-widget.stepper.labelled>
| Prop | Default | Description |
|---|---|---|
| steps |
[]
|
Labels, or arrays: ['label' => 'Payment', 'description' => …, 'href' => …, 'optional' => true, 'locked' => true, 'error' => true]. href makes a done step, or one with an error, a link back to it; description shows when vertical; locked dims a step not reached yet and adds a lock; error marks one that needs attention. |
| current |
1
|
The step you're on, counting from 1; kept between the first and the last. |
| label |
'Progress'
|
The steps' name for screen readers. |
| orientation |
'horizontal'
|
horizontal: a row that shows only the current step's name on phones. vertical: stacked, with descriptions. |
Accessibility
All 6 examples above are checked with axe-core against the WCAG 2.2 A and AA rules, in the light theme and the dark one, both as the page draws and with each popover, dialog, toast and tooltip opened, on every change. A change that fails can't be merged. Where axe can't decide, such as contrast on SVG text, the test measures the colours itself instead of letting it pass.
Automated checks can't judge everything: how it sounds in a screen reader, and how it feels to use from the keyboard, still need a person. Check those on your own pages too.
Source
What bladewell:add stepper writes to your app with the default namespaces. Prefer to copy by hand? Take these files, plus the ones from
the components it also adds , and the theme and base CSS.
resources/views/components/widget/stepper/chevrons.blade.php Show
resources/views/components/widget/stepper/dots.blade.php Show
resources/views/components/widget/stepper/index.blade.php Show
resources/views/components/widget/stepper/labelled.blade.php Show