Filament Modal Notifications Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require wezlo/filament-modal-notifications
   

2. Register the plugin in your Filament panel provider (e.g., AppServiceProvider or PanelServiceProvider):

   use Wezlo\FilamentModalNotifications\FilamentModalNotificationsPlugin;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               FilamentModalNotificationsPlugin::make(),
           ]);
   }
   

3. First use case: Convert a standard notification to a modal by chaining ->asModal():

   Notification::make()
       ->title('Success!')
       ->body('Your action was completed.')
       ->success()
       ->asModal(); // <-- One-line change
   

Where to Look First

• README: Focus on the "Features" section for quick reference on capabilities.
• Plugin Configuration: Check config/filament-modal-notifications.php (auto-generated) for defaults like default_width or auto_close.
• Livewire Events: Debugging? Inspect filament-modal-notifications events in your browser’s DevTools (Network tab).

Implementation Patterns

Core Workflow

1. Standard Notifications → Modals: Replace Notification::make()->toast() with Notification::make()->asModal(). Example:

   Notification::make()
       ->title('Warning')
       ->body('Are you sure?')
       ->warning()
       ->actions([
           Action::make('Confirm')
               ->color('danger')
               ->action(fn () => $this->deleteRecord()),
           Action::make('Cancel')
               ->action(fn () => Notification::make()->close()),
       ])
       ->asModal();
   

2. Conditional Modals: Use ->asModal($condition) to fallback to a toast when needed:

   if ($isCritical) {
       Notification::make()->asModal();
   } else {
       Notification::make()->toast(); // Falls back to default
   }
   

3. Queue Management: Modals auto-queue. Fire multiple notifications in a row:

   Notification::make()->title('Step 1')->asModal();
   Notification::make()->title('Step 2')->asModal(); // Waits for dismissal
   

Integration Tips

• Custom Actions: Override the default "Close" button by defining ->actions().
• Dynamic Content: Use Livewire properties to update modal content post-render:

  $this->dispatch('filament-modal-notifications::render', data: [
      'title' => 'Live Update',
      'body' => $this->dynamicContent,
  ]);
  

• Panel-Level Defaults: Configure defaults in the plugin registration:

  FilamentModalNotificationsPlugin::make()
      ->defaultWidth('50%')
      ->autoClose(false)
      ->closeButtonLabel('Got it');
  

Gotchas and Tips

Pitfalls

1. Session Key Conflicts:

   • Modals use a dedicated session key (filament-modal-notifications). If you manually clear sessions, modals may not render. Use Notification::make()->close() instead.
   • Fix: Ensure no other packages override this key.

2. Livewire Event Race Conditions:

   • Rapid-fire notifications might cause UI glitches if the previous modal hasn’t fully dismissed.
   • Fix: Debounce notifications or use ->asModal()->delay(1000) (if supported).

3. Action Button Overrides:

   • If you define ->actions(), the auto-added "Close" button disappears. Add it explicitly if needed:

     ->actions([
         Action::make('Close')->action(fn () => Notification::make()->close()),
     ]);
     

4. Filament 4 vs. 5:

   • The package supports both, but some notification methods (e.g., icon()) may behave differently. Test in your target Filament version.

Debugging

• Check Livewire Events: Open DevTools → Network tab → Filter by filament-modal-notifications. Look for render or close events.
• Log Session Data: Dump the session key to verify modal state:

  dd(session('filament-modal-notifications'));
  

• Disable Auto-Close: Set auto_close: false in config to inspect modal behavior without dismissal.

Extension Points

1. Custom Modal Views: Override the default modal template by publishing and modifying the view:

   php artisan vendor:publish --tag=filament-modal-notifications-views
   

   Edit resources/views/vendor/filament-modal-notifications/modal.blade.php.

2. Plugin Configuration: Extend the plugin class to add custom logic:

   class CustomModalNotificationsPlugin extends FilamentModalNotificationsPlugin
   {
       public function register()
       {
           // Add custom Livewire listeners or session handlers
       }
   }
   

3. Conditional Rendering: Use the rendered event to hook into modal lifecycle:

   Notification::make()
       ->asModal()
       ->on('rendered', fn () => $this->logModalRender());