Wire Elements Modal Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require wire-elements/modal
   

   Ensure your project uses Livewire v3 (check laravel/livewire version in composer.json).

2. Publish Assets (if needed):

   npm install && npm run dev
   

   The package includes Tailwind CSS by default—customize via your existing tailwind.config.js.

3. First Modal Usage:

   @livewire('modal')
   <button wire:click="$dispatch('openModal', {component: 'user.create'})">
       Create User
   </button>
   

4. Define a Modal Component: Create a Livewire component (e.g., app/Http/Livewire/User/Create.php) and register it in ModalServiceProvider (see Implementation Patterns).

First Use Case: CRUD Modal

• Trigger: Dispatch an event from a button/click handler.
• Component: Create a dedicated Livewire component for the modal content.
• Close: Use $dispatch('closeModal') in the component’s methods.

Example:

<!-- Button to open modal -->
<button wire:click="$dispatch('openModal', {component: 'user.edit', id: 1})">
    Edit User
</button>

<!-- Modal content (auto-rendered by the package) -->

Implementation Patterns

1. Component Registration

Register your modal components in the service provider (auto-discovered via config/livewire.php):

// app/Providers/ModalServiceProvider.php
public function register()
{
    $this->app->make(\WireElements\Modal\ModalService::class)->register([
        'user.create' => \App\Http\Livewire\User\Create::class,
        'user.edit'   => \App\Http\Livewire\User\Edit::class,
    ]);
}

2. Dynamic Data Passing

Pass data via the openModal event payload:

<button wire:click="$dispatch('openModal', {
    component: 'user.view',
    data: { id: 5, name: 'John Doe' }
})">
    View Profile
</button>

Access in the component:

public $modalData;

protected $listeners = ['openModal' => 'handleModal'];

public function handleModal($data)
{
    $this->modalData = $data['data'];
}

3. Reusable Modal Templates

Extend the default modal template by publishing views:

php artisan vendor:publish --tag=wire-elements-modal-views

Customize resources/views/vendor/wire-elements-modal/modal.blade.php.

4. Nested Modals

Use unique keys to stack modals:

<button wire:click="$dispatch('openModal', {
    component: 'settings.profile',
    key: 'profile-settings'
})">
    Profile Settings
</button>

5. Integration with Forms

Combine with Livewire forms for seamless CRUD:

// In your modal component
public function save()
{
    $this->validate([...]);
    User::create($this->formData);
    $this->dispatch('closeModal');
    $this->dispatch('modalSaved');
}

Gotchas and Tips

Pitfalls

1. Livewire v3 Compatibility:

   • Ensure all $emit calls are replaced with $dispatch (see README).
   • Use wire:ignore on modal containers to prevent re-renders:

     <div wire:ignore x-data="{ open: false }">
         @livewire('modal')
     </div>
     

2. Component Not Found:

   • Verify components are registered in ModalServiceProvider.
   • Check for typos in component keys (case-sensitive).

3. Styling Conflicts:

   • The package uses Tailwind by default. Override classes in your modal template:

     <div class="bg-white dark:bg-gray-800 p-6 rounded-lg shadow-lg">
         {{ $slot }}
     </div>
     

4. Event Listener Leaks:

   • Remove listeners in mount() to avoid memory leaks:

     public function mount()
     {
         $this->removeListener('openModal');
     }
     

Debugging Tips

• Check Events: Use wire:click="$dispatch('openModal', {component: 'test'})" and inspect browser console for errors.
• Log Modal Data: Add a dd($this->modalData) in your component’s handleModal method.
• Clear Cache: After registering new components, run:

  php artisan view:clear && php artisan config:clear
  

Extension Points

1. Custom Modal Sizes: Add size classes via the openModal payload:

   $dispatch('openModal', {
       component: 'user.create',
       size: 'lg' // Maps to Tailwind's w-full max-w-lg
   })
   

   Extend the template to handle size:

   @if($size === 'lg')
       <div class="max-w-2xl">
   @else
       <div class="max-w-md">
   @endif
   

2. Modal Footers: Pass footer content via the payload:

   $dispatch('openModal', {
       component: 'user.delete',
       footer: '<button wire:click="confirm">Delete</button>'
   })
   

   Render in the template:

   @if(isset($footer))
       <div class="modal-footer">
           {!! $footer !!}
       </div>
   @endif
   

3. Animation Hooks: Use Alpine.js to add transitions:

   <div x-transition
        x-show="open"
        @before-enter="open = true"
        @after-leave="open = false">
       @livewire('modal')
   </div>