Laravel Livewire Multistep Form Laravel Package

Getting Started

• Install with composer require codegenie-bec/laravel-livewire-multistep-form (confirm the exact vendor/package string from the README — the repo is Codegenie-BE/laravel-livewire-multistep-form). v1.0.0 is the first stable release and targets Livewire 3; check composer.json for the Laravel/PHP matrix before upgrading an existing app, since the release notes mention explicit compatibility gates.
• Publish the package assets (config, views, and translation files) before touching any code:

  php artisan vendor:publish --provider="Codegenie\LivewireMultistepForm\...ServiceProvider"
  

  If the tag list is available, prefer targeted tags (--tag=config, --tag=views, --tag=lang) so you don't fork files you don't intend to maintain.
• Look first at: config/ (step/submission behaviour), resources/views/ (wizard markup and accessibility scaffolding), and src/ for the base wizard component or trait. That base class is the contract you extend — everything else is presentation.
• First use case: an onboarding or checkout form where each step owns its own validation. Scaffold a component, declare your steps, move your existing rules() into per-step rules, and render the package's wizard view. You should have a working two-step form in well under an hour; the review/submit step is the part worth reading the source for before you build on it.

Implementation Patterns

• Declare steps declaratively, not imperatively. Put your step keys/labels in a single method rather than scattering if ($step === 2) checks through the Blade file. This keeps the progress indicator, focus management, and navigation buttons in sync automatically, and it's the surface the package's dynamic-step handling expects.
• Per-step validation is the point of the package. Define rules per step, then let the wizard gate nextStep(). Keep the full rule set available for the final submit so the review step re-validates everything — a user can reach the last step having only ever validated step-by-step.
• Dynamic steps: the release notes call out dynamic step handling specifically. Branch on already-collected data (e.g. skip a company step for private customers) before the user has entered data for the branch, and always re-enter at the first step when the shape of the flow changes. Recompute the step list in one place, not in Blade.
• Submission contract: funnel persistence into the single submit hook the package exposes rather than calling save() from a button click. Wrap multi-table writes in DB::transaction(), and remember the wizard is re-renderable — guard against double submission with an idempotency check or a $submitting flag.
• Server-only rules (v1.0.0, PR #11): exists, unique, current_password, password and similar are now supported. Keep them in the step rules where they semantically belong, but expect the validation error to arrive only after a server round-trip.
• Accessibility is a feature you inherit, not one you bolt on. The package manages focus on step transitions and emits scoped, localizable aria markup (PRs #3, #6, #14). Publish translations if your copy or language doesn't match, and put a single <h2>/legend per step so screen-reader users get the step context the markup assumes.
• Composition: render the wizard from a page-level Livewire component or a plain controller view; keep analytics/step-tracking in a listener on the step-changed event rather than inside the wizard.

Gotchas and Tips

• wire:key on repeated fields. If a step renders a list (addresses, line items) the DOM diff will happily reuse the wrong input across steps. Give each row a stable key derived from your data, not the loop index.
• Select fields. PR #5 hardened select correctness — that usually means placeholder '' vs null handling. Bind to a typed property, cast enums explicitly, and don't mix wire:model and wire:model.live on the same field; the deferred update will silently keep the stale value when you jump steps.
• Uploads don't survive a refresh. Temporary uploads live on the component. If a user goes back a step and the component is re-mounted (full-page navigation rather than a Livewire transition), they're gone — keep uploads on the last data-entry step, or persist them out-of-band as soon as they land.
• Step index drift. Going back after a conditional step is added/removed is the classic bug: the index points at a different step. Navigate by step key, not integer, and clamp defensively when hydrating from a query string or session.
• Don't fight the focus management. PR #14 deliberately moves focus on step change. Custom autofocus attributes or a JS focus() on mount will race it and produce a jump. Style the package's focus target instead.
• Config changes need a cache bust. Anything published to config/ is inert after php artisan config:cache — re-run it on deploy, and never read config dynamically inside a loop that runs per render.
• Debugging: @dump($this->currentStep) in the wizard view plus Livewire::listen/the browser's Livewire devtools payload will tell you whether the problem is state or markup. If a step renders the previous step's data, it's almost always a wire:key or a non-persisted public property, not the package.
• Extension points before forking: override the Blade views (publish them), override methods on your component subclass, and use the config for behavioural toggles. Vendor-patching is the wrong answer for a package that just shipped its first stable release with an active CI gate — expect patch releases, and pin ^1.0 so you get them.