Wiretoast Laravel Package

Getting Started

To begin using wiretoast in a Laravel/Livewire project, follow these minimal steps:

1. Install the Package

   composer require edulazaro/wiretoast
   

2. Load Assets

   • For Vite projects (recommended): Import the CSS and JS in resources/js/app.js and resources/css/app.css:

     import '@wiretoast/js/wiretoast.js';
     import '@wiretoast/css/wiretoast.css';
     

     Add the component to your layout (e.g., resources/views/layouts/app.blade.php):

     <x-wiretoast />
     

   • For non-Vite projects: Publish assets and inject them in Blade:

     php artisan vendor:publish --tag=wiretoast-assets
     

     <x-wiretoast :assets="true" />
     

3. Trigger Your First Toast In a Livewire component, use the $this->notify() helper:

   $this->notify('Success! Your changes were saved.', 'success');
   

   Or in Alpine.js:

   <button @click="$dispatch('notify', { message: 'Hello!', type: 'info' })">
       Show Toast
   </button>
   

4. Verify Open your browser’s dev tools (F12) and check the rendered toasts in the DOM under .wt-toast.

First Use Case: Display a success toast after a form submission in Livewire.

// In your Livewire component
public function submitForm()
{
    $this->validate([...]);
    // Save logic...
    $this->notify('Form submitted successfully!', 'success');
}

Implementation Patterns

Core Workflows

1. Livewire Integration

• Default Notifications: Use $this->notify() in Livewire components for server-side triggered toasts.

  $this->notify('Operation failed.', 'error');
  

• Custom Options: Pass an array for advanced control (position, timeout, etc.).

  $this->notify('Warning!', 'warning', [
      'position' => 'bottom-center',
      'timeout'  => 8000,
      'progress' => true,
  ]);
  

• Grouping: Collapse repeated toasts of the same type.

  $this->notify('Duplicate entry.', 'error', true); // Legacy group mode
  // OR
  $this->notify('Duplicate entry.', 'error', ['group' => true]);
  

2. Alpine.js/Vanilla JS

• Dispatch Events: Use $dispatch in Alpine.js for frontend-triggered toasts.

  <button @click="$dispatch('notify', {
      title: 'Update',
      message: 'Profile updated at ' + new Date().toLocaleTimeString(),
      type: 'success',
      position: 'top-right'
  })">
      Update Profile
  </button>
  

• Global JS API: Use window.notify() for non-Alpine contexts.

  window.notify('Direct JS toast!', 'info');
  

3. Theming and Dark Mode

• Component Props: Set theme/mode globally in the Blade component.

  <x-wiretoast theme="glass" mode="dark" default-position="bottom-right" />
  

• Dynamic Theming: Override themes via CSS variables or data attributes.

  /* Custom theme */
  [data-wt-theme="brand"] .wt-toast {
      --wt-bg: #2d3748;
      --wt-text: #ffffff;
  }
  

  <x-wiretoast theme="brand" />
  

4. Asset Management

• Vite: Leverage Vite’s bundling for zero HTTP requests.

  // vite.config.js
  export default defineConfig({
      resolve: {
          alias: {
              '@wiretoast': path.resolve(__dirname, 'vendor/edulazaro/wiretoast/resources'),
          },
      },
  });
  

• Non-Vite: Publish assets to public/vendor/wiretoast/ and inject via Blade.

Integration Tips

Laravel Controllers

Use the notify helper in controllers for non-Livewire responses (requires manual JS dispatch):

return redirect()->route('dashboard')->with([
    'toast' => ['message' => 'Redirect success!', 'type' => 'success']
]);

Then dispatch in a Blade script:

@if(session('toast'))
    <script>
        window.notify({{ json_encode(session('toast')) }});
    </script>
@endif

Livewire + Alpine Sync

Sync Livewire and Alpine toasts by dispatching Alpine events in Livewire:

// Livewire component
public function syncToast()
{
    $this->dispatch('notify-alpine', message: 'Synced toast!');
}

<!-- Alpine -->
<script>
    window.addEventListener('notify-alpine', (e) => {
        $dispatch('notify', {
            message: e.detail.message,
            type: 'info'
        });
    });
</script>

Form Validation Feedback

Use wire:submit to show toasts on validation errors:

<form wire:submit="save">
    <!-- Fields -->
    @error('email') <span class="error">{{ $message }}</span> @enderror
    <button type="submit">Save</button>
</form>

@script
    window.addEventListener('livewire:submit', (e) => {
        if (e.detail.success) {
            $dispatch('notify', { message: 'Saved!', type: 'success' });
        }
    });
@endscript

API Response Handling

Intercept API responses in Livewire and notify users:

// Livewire component
public function fetchData()
{
    try {
        $data = Http::get('...')->json();
        $this->notify('Data fetched successfully!', 'success');
    } catch (\Exception $e) {
        $this->notify($e->getMessage(), 'error');
    }
}

Gotchas and Tips

Pitfalls

1. Asset Injection Conflicts

   • Issue: Forgetting to set :assets="true" in non-Vite projects causes missing CSS/JS.
   • Fix: Always verify asset injection in Blade:

     <x-wiretoast :assets="true" /> <!-- Non-Vite -->
     <x-wiretoast /> <!-- Vite -->
     

2. Livewire Hydration Mismatches

   • Issue: Toasts may flicker or duplicate during Livewire hydration if not handled carefully.
   • Fix: Use wire:ignore on the toast container or clear toasts in mount():

     public function mount()
     {
         $this->clearToasts(); // Hypothetical; use Alpine/Livewire events instead
     }
     

3. Dark Mode Overrides

   • Issue: Custom dark mode classes (e.g., .dark) may conflict with prefers-color-scheme.
   • Fix: Explicitly set mode="dark" or mode="light" in the component to override OS preferences.

4. Progress Bar Timing

   • Issue: The progress bar may not update correctly if timeout is set to 0 (persistent toast).
   • Fix: Ensure timeout is a positive integer (e.g., 5000) for progress bars to work.

5. Group Mode Quirks

   • Issue: Grouped toasts may not collapse as expected if the type or message differs slightly (e.g., whitespace).
   • Fix: Standardize message types for grouping (e.g., trim strings or use a unique key).

6. Vite HMR Delays

   • Issue: Toast styles may not update immediately during Vite HMR due to CSS caching.
   • Fix: Hard-refresh the browser or use ?t=... cache-busting queries in development.

Debugging Tips

1. Inspect Toast State Use browser dev tools to check:

   • Rendered DOM: .wt-toast classes, data attributes (data-wt-*).
   • Applied styles: Override CSS variables in the :root scope to test themes.
   • Event listeners: Verify $dispatch events in Alpine or window.notify calls.

2. Disable Auto-Dismiss Temporarily set timeout: 0 to debug persistent toasts:

   window.notify('Debug toast', 'info', { timeout: 0 });
   

3. Log Notifications Add a debug listener in Alpine to log toast payloads:

   <script>
       window.addEventListener('notify', (e) => {
           console.log('Toast payload