Getting Started

Minimal Steps

Installation:

composer require theabhishekin/livewire-toast

Add Toast Container: Place @livewire('toast-container') in your main layout (e.g., resources/views/layouts/app.blade.php), typically near the <body> opening tag for optimal visibility.
Import JavaScript: Add the toast script to your entry file (e.g., resources/js/app.js):
```
import '../../vendor/theabhishekin/livewire-toast/resources/js/toast';
```

First Toast: Dispatch a toast from a Livewire component:

$this->dispatch('toast', [
    'title' => 'Success!',
    'type' => 'success',
]);

First Use Case

Trigger a success toast after a form submission:

public function save()
{
    $this->validate([...]);

    // Save logic...

    $this->dispatch('toast', [
        'title' => 'Saved successfully!',
        'type' => 'success',
        'description' => 'Your changes have been saved.',
    ]);

    return redirect()->to('/');
}

Implementation Patterns

Core Workflows

Component Integration:
- Use $this->dispatch('toast', [...]) in Livewire methods (e.g., mount(), updatedProperty(), or event handlers).
- Example for conditional toasts:
```
if ($this->isValid()) {
    $this->dispatch('toast', ['title' => 'Valid!', 'type' => 'success']);
}
```

Dynamic Toasts:

Pass variables from Livewire to Alpine via dispatch:

$this->dispatch('toast', [
    'title' => 'User ' . $user->name . ' created',
    'type' => 'info',
]);

Action Buttons:

Add interactive buttons to toasts:

$this->dispatch('toast', [
    'title' => 'Action required',
    'type' => 'warning',
    'actions' => [
        ['text' => 'Retry', 'url' => route('retry')],
        ['text' => 'Dismiss', 'event' => 'toast.dismiss'],
    ],
]);

Positioning:

Override default position (e.g., bottom-right) via config or per-toast:

$this->dispatch('toast', [
    'title' => 'Alert',
    'position' => 'bottom-right',
]);

Auto-Dismiss:

Control duration (ms) globally in config/livewire-toast.php or per-toast:

$this->dispatch('toast', [
    'title' => 'Temporary',
    'duration' => 3000, // 3 seconds
]);

Integration Tips

Dark Mode: Ensure your theme supports data-[dark] attributes (handled automatically via Alpine).
Stacking: Limit visible toasts via maxVisible in config (default: 5).

Livewire Events: Listen for toast events in Alpine:

document.addEventListener('toast.show', (e) => {
    console.log('Toast shown:', e.detail);
});

Custom Styling: Extend the toast container’s classes (e.g., .livewire-toast-container) in your CSS.

Gotchas and Tips

Pitfalls

JavaScript Loading Order:
- Ensure toast.js is imported after Alpine.js (if not using Vite/Laravel Mix auto-ordering).
- Fix: Move the import to the end of app.js or use defer.
Duplicate Toasts:
- Rapid dispatches may stack unexpectedly. Use duration: 0 for persistent toasts or debounce dispatches:
```
if (!$this->hasToastShown) {
    $this->dispatch('toast', [...]);
    $this->hasToastShown = true;
}
```
Alpine Conflicts:
- If using other Alpine-based packages, namespace Alpine components in the toast script:
```
// In toast.js, replace `Alpine.store` with:
window.Alpine.store('toast', { ... });
```
Livewire Re-renders:
- Toasts may flicker if the container re-renders. Anchor the container to a stable DOM node (e.g., #app).
Config Publishing:
- Forgetting to publish config (php artisan vendor:publish --tag=livewire-toast-config) means using defaults only.

Debugging

Toast Not Showing?:
- Check browser console for Alpine/JS errors.
- Verify the container is rendered (@livewire('toast-container') exists in the DOM).
- Ensure no JS errors block the toast script.

Styling Issues:

Override default classes (e.g., .livewire-toast) in your CSS:

.livewire-toast { --tw-bg-opacity: 0.95; } /* Example: Adjust backdrop */

Event Listeners:

Debug Alpine events with:

window.Alpine.on('toast.show', (e) => console.log(e.detail));

Extension Points

Custom Toast Types:
- Extend the types array in config to add themes (e.g., ['custom']).
- Override colors in CSS:
```
.livewire-toast-custom { --tw-bg-color: #3b82f6; }
```
Global Toast State:
- Access toasts via Alpine store:
```
const toasts = Alpine.store('toast').toasts;
```

Server-Side Logic:

Use Livewire hooks to trigger toasts:

protected $listeners = ['toast.trigger' => 'showToast'];

public function showToast($data) {
    $this->dispatch('toast', $data);
}

Testing:

Mock toasts in PHPUnit:

$this->dispatchBrowserEvent('toast', ['title' => 'Test']);
$this->assertLivewireDispatches('toast');

Performance:

For high-frequency toasts (e.g., real-time updates), batch dispatches:

$this->dispatch('toast.batch', [
    ['title' => 'Update 1'],
    ['title' => 'Update 2', 'type' => 'info'],
]);

Livewire Toast Laravel Package