Livewire Wizard Form Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require rinodrummer/livewire-wizard-form
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="RinoDrummer\LivewireWizardForm\LivewireWizardFormServiceProvider"
   

2. First Use Case: Basic Wizard Form Create a Livewire component with the HasWizardForm trait:

   use RinoDrummer\LivewireWizardForm\Traits\HasWizardForm;
   
   class MultiStepForm extends Component
   {
       use HasWizardForm;
   
       public function mount()
       {
           $this->wizardForm()->steps([
               'step1' => 'Step 1',
               'step2' => 'Step 2',
               'step3' => 'Step 3',
           ]);
       }
   
       public function render()
       {
           return view('livewire.multi-step-form');
       }
   }
   

3. Blade Integration Use the provided directives in your view:

   @wizardForm
   @wizardStep('step1')
       <!-- Step 1 content -->
   @endwizardStep
   
   @wizardStep('step2')
       <!-- Step 2 content -->
   @endwizardStep
   

4. Navigation Add buttons to control flow:

   @wizardPreviousButton
   @wizardNextButton
   @wizardSubmitButton
   

Implementation Patterns

Core Workflows

1. Step Management Dynamically add/remove steps via methods:

   $this->wizardForm()->addStep('new_step', 'New Step');
   $this->wizardForm()->removeStep('step2');
   

2. Validation Integration Use validateStep() to enforce validation per step:

   public function nextStep()
   {
       $this->validateStep('step1', [
           'email' => 'required|email',
       ]);
       $this->wizardForm()->next();
   }
   

3. Data Persistence Bind form data to properties:

   public $step1Data = [];
   public $step2Data = [];
   
   protected $rules = [
       'step1Data.*' => 'required',
       'step2Data.*' => 'required',
   ];
   

4. Custom Logic per Step Override onStepEnter()/onStepLeave():

   public function onStepEnter($stepName)
   {
       if ($stepName === 'step3') {
           $this->fetchAdditionalData();
       }
   }
   

Advanced Patterns

• Conditional Steps Hide/show steps dynamically:

  public function render()
  {
      return view('livewire.multi-step-form')->with([
          'showStep3' => $this->shouldShowStep3(),
      ]);
  }
  

• Progress Tracking Use $this->wizardForm()->currentStep() and $this->wizardForm()->progress() in Blade:

  Progress: {{ $this->wizardForm()->progress() }}%
  

• Multi-Form Integration Combine with other Livewire components:

  public function mount()
  {
      $this->wizardForm()->steps(['step1', 'step2']);
      $this->otherComponent = new OtherComponent();
  }
  

Gotchas and Tips

Common Pitfalls

1. State Management

   • Issue: Wizard state resets on page refresh.
   • Fix: Use session() or database to persist progress:

     public function mount()
     {
         $this->wizardForm()->steps(['step1', 'step2']);
         $this->wizardForm()->setCurrentStep(session('wizard_step', 'step1'));
     }
     
     public function nextStep()
     {
         session(['wizard_step' => $this->wizardForm()->currentStep()]);
     }
     

2. Validation Quirks

   • Issue: Validation errors persist across steps.
   • Fix: Clear errors explicitly:

     public function nextStep()
     {
         $this->resetErrorBag();
         $this->validateStep('step1', [...]);
     }
     

3. Blade Directive Scope

   • Issue: @wizardStep directives must be nested inside @wizardForm.
   • Fix: Validate Blade structure:

     @wizardForm
         @wizardStep('step1') <!-- Correct -->
             <!-- Content -->
         @endwizardStep
     @endwizardForm
     

4. Performance with Many Steps

   • Issue: Large step lists slow down rendering.
   • Fix: Lazy-load steps or use partials:

     @wizardStep('step1')
         @livewire('step1-content', key($this->wizardForm()->currentStep()))
     @endwizardStep
     

Debugging Tips

• Log Current Step:

  dd($this->wizardForm()->currentStep());
  

• Inspect Rules:

  dd($this->rules);
  

• Check State:

  dd($this->wizardForm()->getState());
  

Extension Points

1. Custom Transitions Override transitionToStep():

   protected function transitionToStep($stepName)
   {
       // Custom logic (e.g., analytics, logging)
       parent::transitionToStep($stepName);
   }
   

2. Step Templates Create reusable step templates:

   @component('wizard.step-template', ['step' => $step])
       @slot('content')
           <!-- Dynamic content -->
       @endslot
   @endcomponent
   

3. Event Listeners Listen to step changes:

   $this->wizardForm()->on('stepChanged', function ($step) {
       // Handle step change
   });
   

4. Theming Override default styles via CSS:

   .wizard-step.active {
       background: #your-color;
   }