Weave Code
Laravel Livewire Wizard Laravel Package
spatie/laravel-livewire-wizard
Build multi-step Livewire wizards with lightweight components. Each step is its own Livewire component with full access to Livewire features, plus easy control over which step displays.
Build wizards using Livewire
Frequently asked questions about Laravel Livewire Wizard
- How do I install spatie/laravel-livewire-wizard in a Laravel app?
- Install it with Composer using composer require spatie/laravel-livewire-wizard. There are no migrations to run, no config file to publish, no environment variables to set and no external services to connect. Integration effort is almost entirely in writing your own step components and Blade views. Make sure your installed Livewire version matches the package major you pull in.
- Which Livewire version does laravel-livewire-wizard require?
- The current 3.x line requires livewire/livewire ^4.3.4, so it is a hard gate on Livewire 4. If your application is still on Livewire 3, you must stay on the package's 2.x line because major versions track Livewire majors: 2.0.0 for Livewire 3 and 3.0.0 for Livewire 4. Confirm your Livewire version and upgrade appetite before adopting, since upgrading Livewire and upgrading this package become the same project.
- How do I define the steps of a wizard?
- Create a component that extends Spatie\LivewireWizard\Components\WizardComponent and implement a steps() method that returns an ordered array of step component class names. The package renders the step that is currently active based on that array. The order you return is the order the wizard moves through, so you control the flow declaratively in one place.
- What is a StepComponent and how does it differ from a normal Livewire component?
- A step extends Spatie\LivewireWizard\Components\StepComponent, which itself extends Livewire\Component. That means every Livewire feature you already use, such as public properties, validation, computed properties, actions and events, works inside a step. The wizard is a thin composition layer rather than a new runtime, so there is no separate state store or folder convention imposed on you. You just write normal Livewire components and declare them as steps.
- How do I share state or read data from another step in the wizard?
- State sharing across steps is a documented first-class capability: a step can access the state of other steps in the same wizard. Since 2.1.0 there is a forStepClass() convenience method that makes retrieving another step's component instance straightforward. This shared-state behaviour is usually the main reason to adopt the package instead of hand-rolling step navigation. Keep in mind the state lives in the Livewire component lifecycle, not in a database.
- Does the package include a progress bar, next and back buttons, or other wizard UI?
- No. The package is deliberately headless: it ships no navigation UI, no CSS and no Blade scaffolding. It only controls which step component is rendered, leaving the progress indicator, next and back buttons, cancel and exit actions and confirmation modals to you. That makes it easy to slot under an existing design system, but the wizard chrome is your engineering cost, not the vendor's.
- How do I test a wizard step in Laravel with Pest or PHPUnit?
- Steps are Livewire components, so normal Livewire testing applies, and the package adds a dedicated Component::testStep helper that was introduced in 2.4.0. Since 3.1.0 that helper also supports mounting a step with parameters. Per-step tests are useful, but you should also write integration tests that walk the full step sequence, because state-correctness regressions between steps have occurred in past releases and are easy to miss in isolated tests.
- Does the wizard keep the user's progress after a page refresh?
- There is no built-in durability of wizard progress. State lives in the Livewire component lifecycle, so a page refresh, session expiry, back-button navigation, or a mid-flow deploy that renames component classes can drop the user's progress. Whether that is acceptable is a product decision per flow, and adding persistence is the single largest hidden scope item when adopting the package. Plan for it explicitly on anything long-running like onboarding or checkout.
- Can a user skip ahead to a later step or submit a step out of order?
- The package controls which step is displayed, but it does not enforce step order on the server. It cannot stop a malicious client from posting a payload to a later step's component directly. Any wizard that commits money, entitlements or irreversible records needs server-side guards that you write yourself, such as re-validating prerequisites in the action that persists data. Treat step order as UI convenience, not a security boundary.
- Is spatie/laravel-livewire-wizard actively maintained, and what are the alternatives?
- It is a Spatie first-party package with an official documentation site, a changelog, tagged releases, a demo application repository and an active Dependabot and pull request pipeline, and the maintainers follow Livewire releases promptly. The main risks are tight version coupling to Livewire and single-maintainer concentration inside a healthy organisation, and the low number of Packagist dependents means you would be an early adopter rather than that the package is unsound. Alternatives are hand-rolling step state in a single Livewire component or using a more opinionated wizard package that ships its own UI; this one wins when you want full Livewire power per step with no scaffolding.
Weaver
How can I help you explore Laravel packages today?