Livewire Modal Sheet Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require sobitnl/livewire-modal-sheet
   

2. Add Livewire Directive: Place @livewire('livewire-modal-sheet') in your layout file (typically before </body>). This initializes the modal manager.

3. First Modal Usage:

   use Sobitnl\LivewireModalSheet\LivewireModalSheet;
   
   // In your Livewire component
   public function openModal()
   {
       LivewireModalSheet::open('modal-name', 'ModalComponent', [
           'data' => 'passed_to_modal',
       ]);
   }
   

   <!-- In your Blade view -->
   <button wire:click="openModal">Open Modal</button>
   

4. Define Modal Component: Create a Livewire component (e.g., ModalComponent) and register it in LivewireModalSheet::register() if needed.

First Use Case: Simple Modal

// In your Livewire component
public function showUserProfile($userId)
{
    LivewireModalSheet::open('user-profile', 'UserProfileModal', [
        'userId' => $userId,
    ]);
}

<!-- Blade -->
<button wire:click="showUserProfile(1)">View Profile</button>

Implementation Patterns

Modal Hierarchy & State Management

1. Nested Modals: Open modals from within other modals by reusing LivewireModalSheet::open().

   // Inside a modal component
   public function openChildModal()
   {
       LivewireModalSheet::open('child-modal', 'ChildModalComponent');
   }
   

2. Passing Data: Use arrays or objects to pass data between parent and child modals.

   LivewireModalSheet::open('modal', 'ModalComponent', [
       'config' => ['key' => 'value'],
       'user' => $user,
   ]);
   

3. Closing Modals:

   // Close current modal
   LivewireModalSheet::close();
   
   // Close specific modal
   LivewireModalSheet::close('modal-name');
   

Integration with Livewire

1. Event Handling: Listen for modal events in your Livewire components:

   protected $listeners = ['modalOpened' => 'handleModalOpened'];
   
   public function handleModalOpened($event)
   {
       if ($event['name'] === 'modal-name') {
           // Handle modal open logic
       }
   }
   

2. Dynamic Registration: Register modals dynamically (e.g., in boot()):

   public function boot()
   {
       LivewireModalSheet::register('dynamic-modal', 'DynamicModalComponent');
   }
   

3. Modal Configuration: Override default settings (e.g., size, backdrop) via LivewireModalSheet::config():

   LivewireModalSheet::config([
       'defaultSize' => 'lg',
       'backdrop' => true,
   ]);
   

Workflow: Multi-Step Forms

1. Step 1: Open first modal.

   LivewireModalSheet::open('step-1', 'StepOneModal');
   

2. Step 2: From StepOneModal, open next modal with updated data.

   public function proceedToStepTwo($data)
   {
       LivewireModalSheet::open('step-2', 'StepTwoModal', ['data' => $data]);
       LivewireModalSheet::close('step-1'); // Close previous modal
   }
   

Gotchas and Tips

Pitfalls

1. Modal Stacking:

   • Issue: Modals may not close properly if not managed explicitly.
   • Fix: Always call LivewireModalSheet::close() when navigating between modals or completing actions.
   • Tip: Use LivewireModalSheet::closeAll() to reset the stack.

2. State Persistence:

   • Issue: Data passed to modals may not persist if the parent component re-renders.
   • Fix: Use $persistent property in LivewireModalSheet::open():

     LivewireModalSheet::open('modal', 'ModalComponent', [], ['persistent' => true]);
     

3. Tailwind Conflicts:

   • Issue: Custom styles may override modal classes.
   • Fix: Extend the Tailwind config to safelist modal-specific classes:

     safelist: [
         'modal-backdrop', 'modal-content', 'modal-header', // etc.
     ]
     

Debugging

1. Modal Not Showing:

   • Check if @livewire('livewire-modal-sheet') is included in the layout.
   • Verify the modal name matches exactly (case-sensitive).

2. Console Errors:

   • Inspect browser console for missing dependencies (e.g., Alpine.js, which the package may rely on implicitly).

3. State Not Updating:

   • Ensure Livewire components are properly wired and events are dispatched correctly.

Extension Points

1. Custom Animations: Override default animations by extending the package’s Blade views or using custom CSS:

   <!-- In your modal component -->
   <div x-data="{ open: true }" x-show="open" @click.away="open = false">
       <!-- Modal content -->
   </div>
   

2. Global Configuration: Set defaults in AppServiceProvider:

   public function boot()
   {
       LivewireModalSheet::config([
           'backdrop' => false,
           'defaultSize' => 'md',
       ]);
   }
   

3. Accessing Modal Data: Retrieve modal data in parent components via LivewireModalSheet::getModalData('modal-name').

Pro Tips

1. Reusable Modal Components: Create base modal components with shared logic (e.g., BaseModalComponent) and extend them for specific use cases.

2. Modal Events: Leverage modalOpened, modalClosed, and modalUpdated events for cross-component communication:

   protected $listeners = [
       'modalOpened' => 'syncModalState',
   ];
   

3. Performance: For heavy modals, use wire:ignore to prevent unnecessary re-renders:

   <div wire:ignore>
       @livewire('HeavyModalComponent')
   </div>