Notifications Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require filament/notifications
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Filament\Notifications\NotificationsServiceProvider"
   

2. Basic Usage Add the HasNotifications trait to your Livewire component:

   use Filament\Notifications\Concerns\HasNotifications;
   
   class MyComponent extends Component
   {
       use HasNotifications;
   
       public function mount()
       {
           $this->notify('Success', 'Your action was completed!');
       }
   

3. First Notification Trigger a notification in a Livewire action:

   public function save()
   {
       // ... save logic
       $this->notify('Success', 'Record saved successfully!');
   }
   

4. View the Notifications The package automatically renders notifications in your Livewire component's view. No additional Blade template is required.

Implementation Patterns

Common Workflows

1. Conditional Notifications

   if ($user->save()) {
       $this->notify('Success', 'Profile updated!');
   } else {
       $this->notify('Error', 'Failed to update profile.', type: 'error');
   }
   

2. Persistent Notifications Use persistent: true for notifications that should not auto-dismiss:

   $this->notify('Info', 'This will stay until dismissed.', persistent: true);
   

3. Custom Icons Pass an icon name (from Heroicons):

   $this->notify('Warning', 'Something went wrong.', icon: 'heroicon-o-exclamation-circle');
   

4. Queueing Notifications For async processing, use queue():

   $this->notify('Processing', 'Your request is being handled...', queue: true);
   

5. Notification Groups Group related notifications (e.g., form validation errors):

   $this->notifyGroup('validation', [
       'name' => 'The name field is required.',
       'email' => 'The email must be valid.',
   ]);
   

6. Customizing Appearance Override the default notification view in resources/views/vendor/filament/notifications/notification.blade.php.

Integration Tips

• Livewire Components: Works seamlessly with any Livewire component.
• Blade Views: Use $this->notifications in Blade templates to manually render notifications.
• JavaScript: Listen for notification events via:

  document.addEventListener('filament-notification', (e) => {
      console.log(e.detail);
  });
  

• Testing: Use assertSeeInNotifications() in Pest/Laravel tests:

  $this->assertSeeInNotifications('Success', 'Record saved!');
  

Gotchas and Tips

Pitfalls

1. Auto-Dismiss Delay Notifications auto-dismiss after 5 seconds by default. Override via config:

   'auto_dismiss' => 3, // seconds
   

2. Queueing Issues Ensure your queue worker is running if using queue: true. Notifications may not appear immediately.

3. Styling Conflicts Custom CSS may override Filament’s default styles. Use !important sparingly or inspect the generated classes.

4. Persistent Notifications Persistent notifications (persistent: true) require manual dismissal. Ensure your UI includes a close button.

5. Livewire Re-renders Notifications may flicker if the component re-renders frequently. Use wire:ignore on the notification container if needed.

Debugging

• Check the Console Errors may appear in the browser console (e.g., missing icons or JS issues).
• Inspect Network Requests Queue-based notifications trigger HTTP requests; verify they’re not being blocked.
• Clear Config Cache If changes to config/filament.php don’t apply:

  php artisan config:clear
  

Extension Points

1. Custom Notification Types Extend the Filament\Notifications\Notification class to add custom logic:

   class CustomNotification extends Notification
   {
       public function __construct(public string $title, public string $message)
       {
           $this->title = $title;
           $this->message = $message;
       }
   
       public function getIcon(): string
       {
           return 'heroicon-o-bell';
       }
   }
   

   Use via:

   $this->notify(new CustomNotification('Title', 'Message'));
   

2. Override Default Views Publish and modify the notification Blade views:

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

3. Add Animation Extend the Tailwind CSS classes in resources/css/app.css:

   .filament-notification-enter-active {
       animation: slide-in 0.3s ease-out;
   }
   

4. Localization Translate notification messages via Laravel’s localization system:

   $this->notify(__('filament::notifications.success'), __('filament::notifications.saved'));