Waziri Livewire Toast Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require waziri123/waziri-livewire-toast
   

   Ensure your project already has Livewire, TailwindCSS, and AlpineJS installed.

2. Add the Toast Component: Place @livewire('livewire-toast') in your main layout file (e.g., resources/views/layouts/app.blade.php). This should be included once globally.

3. First Use Case: Trigger a toast from a Livewire component:

   $this->dispatch('showSuccess', 'Action completed!')->to('livewire-toast');
   

   Or from a Blade view:

   <button wire:click="$dispatchTo('livewire-toast', 'showSuccess', {message: 'Success!'})">
       Click Me
   </button>
   

Implementation Patterns

Core Workflows

1. Dispatching Toasts from Livewire Components: Use $this->dispatch() with predefined methods (showSuccess, showError, showWarning, showInfo) for consistency:

   $this->dispatch('showWarning', 'This is a warning')->to('livewire-toast');
   

2. Customizing Toast Content: Pass additional parameters (e.g., duration, icon) via the params object:

   $this->dispatch('showInfo', 'Custom message', [
       'duration' => 5000, // 5 seconds
       'icon' => '⚠️'
   ])->to('livewire-toast');
   

3. AlpineJS Integration: Use $dispatchTo in Blade views for dynamic triggers:

   <button x-on:click="$dispatchTo('livewire-toast', 'showError', {message: 'Oops!'})">
       Trigger Error
   </button>
   

4. Conditional Toasts: Combine with Livewire logic to show toasts based on state:

   if ($this->save()) {
       $this->dispatch('showSuccess', 'Saved successfully!')->to('livewire-toast');
   } else {
       $this->dispatch('showError', 'Failed to save.')->to('livewire-toast');
   }
   

5. Global Toast Handling: Centralize toast logic in a base Livewire component or service class to avoid repetition.

Integration Tips

1. Tailwind Styling: Override default styles by publishing the package’s assets (if supported) or extend the component’s Blade template:

   php artisan vendor:publish --provider="WAZIRI123\LivewireToast\LivewireToastServiceProvider"
   

   Modify resources/views/vendor/livewire-toast.blade.php.

2. Localization: Pass translated messages dynamically:

   $this->dispatch('showSuccess', __('messages.success'))->to('livewire-toast');
   

3. Queueing Toasts: For high-frequency actions (e.g., bulk operations), queue dispatches to avoid UI lag:

   foreach ($items as $item) {
       $this->dispatch('showInfo', "Processing $item")->to('livewire-toast');
   }
   

4. Testing: Mock dispatches in PHPUnit:

   $this->expectsEvents(ToastDispatched::class);
   $this->dispatch('showSuccess', 'Test')->to('livewire-toast');
   

Gotchas and Tips

Pitfalls

1. Missing Component: Forgetting to include @livewire('livewire-toast') in the layout will result in silent failures. Verify the component is rendered before dispatching.

2. Dispatch Target Mismatch: Ensure the target is always 'livewire-toast':

   // ❌ Wrong (will fail silently)
   $this->dispatch('showSuccess', 'Message')->to('wrong-target');
   
   // ✅ Correct
   $this->dispatch('showSuccess', 'Message')->to('livewire-toast');
   

3. AlpineJS Scope Issues: If using $dispatchTo in nested Alpine components, ensure the Livewire component is in the same root scope or use $dispatch with the full target.

4. Tailwind Conflicts: Custom styles may clash with Tailwind’s default utilities. Use !important sparingly; prefer Tailwind’s utility classes or extend the theme.

Debugging

1. Check Dispatch Events: Use Livewire’s event logging or browser dev tools (Network tab) to verify dispatches:

   window.addEventListener('livewire:dispatch', (e) => {
       console.log('Dispatch:', e.detail);
   });
   

2. Inspect Component State: Add a temporary debug method to the Livewire component:

   public function debugToasts() {
       dd($this->toasts); // Check if toasts are being stored
   }
   

3. Clear Cached Views: If styles/toasts disappear after updates, clear Livewire’s view cache:

   php artisan view:clear
   

Tips

1. Reuse Toast Logic: Create a helper trait for Livewire components:

   trait UsesToasts {
       protected function toastSuccess($message) {
           $this->dispatch('showSuccess', $message)->to('livewire-toast');
       }
   }
   

2. Dynamic Icons: Use Tailwind’s arbitrary values for icons:

   $this->dispatch('showWarning', 'Alert', [
       'icon' => '🔥', // Or use Tailwind classes like 'i-heroicons-exclamation'
   ]);
   

3. Auto-Dismissal: Override default durations (e.g., 3s for errors, 10s for success) via config or dispatch params:

   $this->dispatch('showSuccess', 'Long message', ['duration' => 10000]);
   

4. Accessibility: Ensure toasts include role="alert" and ARIA attributes for screen readers:

   @livewireScripts
   <script>
       document.addEventListener('livewire:init', () => {
           Livewire.on('toast.shown', (toast) => {
               toast.el.setAttribute('role', 'alert');
           });
       });
   </script>
   

5. Performance: For heavy applications, debounce rapid dispatches (e.g., during form validation) to avoid UI jank.