Laravel Livewire Wizard Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ympact/laravel-livewire-wizard
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Ympact\LivewireWizard\LivewireWizardServiceProvider"
   

2. Basic Usage Create a Livewire component extending Wizard:

   use Ympact\LivewireWizard\Wizard;
   
   class MultiStepForm extends Wizard
   {
       public function steps(): array
       {
           return [
               'step1' => 'Step 1',
               'step2' => 'Step 2',
               'step3' => 'Step 3',
           ];
       }
   }
   

3. First Use Case Render the wizard in a Blade view:

   <livewire:multi-step-form />
   

   Define step content in renderStep():

   public function renderStep($step)
   {
       return match($step) {
           'step1' => view('steps.step1'),
           'step2' => view('steps.step2'),
           'step3' => view('steps.step3'),
       };
   }
   

Implementation Patterns

Core Workflows

1. Step Validation Override validateStep() to enforce rules per step:

   public function validateStep($step)
   {
       return match($step) {
           'step1' => $this->validate(['name' => 'required']),
           'step2' => $this->validate(['email' => 'required|email']),
           default => true,
       };
   }
   

2. Dynamic Step Control Use canGoNext()/canGoPrevious() to disable steps:

   public function canGoNext($step)
   {
       return $step === 'step3' || $this->isStepValid($step);
   }
   

3. Step Visibility Hide/show steps dynamically:

   public function isStepVisible($step)
   {
       return $step !== 'step2' || $this->user->isPremium();
   }
   

Integration Tips

• Form Submission Use submit() to handle final submission:

  public function submit()
  {
      $this->validate();
      // Save data
      $this->dispatch('wizard-submitted');
  }
  

• Progress Tracking Access current step via $this->currentStep.

• Custom Styling Extend the default Blade template or use Tailwind/Alpine for UI.

Gotchas and Tips

Pitfalls

1. Validation Timing

   • validateStep() runs before rendering the step. Ensure rules match the step’s form fields.
   • Use validate() in submit() for final validation.

2. State Persistence

   • Wizard state (current step, data) is stored in Livewire’s session. Avoid resetting $this->currentStep manually.

3. Step Naming

   • Steps must be unique strings (e.g., 'step1' not 1). Use kebab-case for readability.

Debugging

• Log Current Step Add to mount():

  \Log::debug('Current step:', [$this->currentStep]);
  

• Check Validation Errors Use $errors->all() in Blade to debug step-specific errors.

Extension Points

1. Custom Transitions Override nextStep()/previousStep() for custom logic:

   public function nextStep()
   {
       if ($this->currentStep === 'step2') {
           $this->dispatch('confirm-before-proceed');
       }
       parent::nextStep();
   }
   

2. Step Metadata Attach data to steps via steps() array:

   return [
       'step1' => [
           'title' => 'Personal Info',
           'icon' => 'user',
       ],
   ];
   

3. Livewire Events Listen for step-changed or wizard-submitted in Blade:

   @script
       Livewire.on('step-changed', step => {
           console.log('Moved to step:', step);
       });
   @endscript
   

Config Quirks

• Default Views The package lacks built-in views. Use the renderStep() method or create custom templates in resources/views/livewire/.

• Livewire 4 Support Not yet implemented (check roadmap). Use at your own risk if upgrading.