AI Skill

---
name: livewire-alert
description: Fluent SweetAlert2 alerts, toasts, confirms, inputs, and loading dialogs for Laravel Livewire 3.x/4.x. Use when working with the jantinnerezo/livewire-alert package or when a user wants SweetAlert2 notifications from Livewire components.
---

# livewire-alert

Fluent PHP API for SweetAlert2 inside Laravel Livewire components. Package: `jantinnerezo/livewire-alert`. Requires PHP 8.1+, Laravel 10+, Livewire 3.x or 4.x, SweetAlert2.

## Install

```bash
composer require jantinnerezo/livewire-alert
npm install sweetalert2
```

Register SweetAlert2 in `resources/js/app.js`:

```js
import Swal from 'sweetalert2'
window.Swal = Swal
```

Optional config publish:

```bash
php artisan vendor:publish --tag=livewire-alert:config
```

## Core API

Use the facade or inject `Jantinnerezo\LivewireAlert\LivewireAlert`. Every builder chain ends with `->show()` (exceptions: `update()`, `close()`).

```php
use Jantinnerezo\LivewireAlert\Facades\LivewireAlert;

LivewireAlert::title('Saved')->success()->show();
```

### Icons

`success()`, `error()`, `warning()`, `info()`, `question()`.

### Text and position

```php
LivewireAlert::title('Item Saved')
    ->text('Stored in the database.')
    ->success()
    ->position('center') // top-start, top-end, center, bottom-start, bottom-end
    ->show();
```

`Position` enum: `Jantinnerezo\LivewireAlert\Enums\Position`. Strings accepted too.

### Toast

`asToast()` preset (top-end, timer, progress bar) or manual `toast()`:

```php
LivewireAlert::title('Saved!')->success()->asToast()->show();

LivewireAlert::title('Welcome')
    ->info()
    ->toast()
    ->position('top-end')
    ->timer(3000)
    ->timerProgressBar()
    ->show();
```

### Timer

```php
LivewireAlert::title('Done')->success()->timer(3000)->timerProgressBar()->show();
LivewireAlert::title('Review')->warning()->timer(null)->withConfirmButton('OK')->show();
```

`timer(null)` disables auto-dismiss.

### Buttons

```php
LivewireAlert::title('Save?')
    ->withConfirmButton('Save')
    ->withCancelButton('Cancel')
    ->withDenyButton('Discard')
    ->confirmButtonColor('#16a34a')
    ->denyButtonColor('#dc2626')
    ->show();
```

Text helpers: `confirmButtonText()`, `cancelButtonText()`, `denyButtonText()`. Color helpers accept any CSS color.

### Confirm dialog

`asConfirm()` = question icon + confirm/deny buttons + no timer.

```php
LivewireAlert::title('Delete?')
    ->text('Are you sure?')
    ->asConfirm()
    ->onConfirm('deleteItem', ['id' => $this->itemId])
    ->onDeny('keepItem', ['id' => $this->itemId])
    ->show();
```

### Button events

Map button results to Livewire methods. Payload arrives as `array $data`.

- `onConfirm($method, $payload)` — confirm button
- `onDeny($method, $payload)` — deny button
- `onDismiss($method, $payload)` — cancel, ESC, backdrop, close

```php
public function deleteItem(array $data)
{
    $id = $data['id'];
}
```

### Inputs

Input value arrives as `$data['value']` in the handler.

```php
LivewireAlert::title('Name')
    ->withTextInput(label: 'Full name', placeholder: 'John Doe')
    ->withConfirmButton('Submit')
    ->onConfirm('saveName')
    ->show();
```

Helpers: `withTextInput`, `withEmailInput`, `withPasswordInput`, `withNumberInput`, `withTextareaInput`, `withSelectInput(options: ['k' => 'Label'])`, `withRadioInput`, `withCheckboxInput` (returns `1` or `null`), `withFileInput`.

### Loading

Non-dismissable spinner. Pair with `close()` when work finishes.

```php
LivewireAlert::title('Saving...')->asLoading()->show();
// long work
LivewireAlert::close();
```

Custom title: `LivewireAlert::asLoading('Uploading...')->show();`

### Update open alert

Mutates the visible alert in place (`Swal.update()`). No flicker. No-op (console warning) if no alert is open. Does not preserve input values or rebind handlers.

```php
LivewireAlert::title('New title')->text('Updated body')->update();

LivewireAlert::update([
    'title' => 'Done',
    'icon' => 'success',
]);
```

Pair with `wire:poll` or `Bus::batch()` for live progress.

### Flash (post-redirect)

```php
// component A
session()->flash('saved', ['title' => 'Saved!', 'text' => 'Done.']);
$this->redirect('/dashboard');

// component B mount()
public function mount()
{
    if (session()->has('saved')) {
        LivewireAlert::title(session('saved.title'))
            ->text(session('saved.text'))
            ->success()
            ->show();
    }
}
```

### Customization

- `imageUrl()`, `imageWidth()`, `imageHeight()`, `imageAlt()`
- `customClass(['popup' => '...', 'confirmButton' => '...'])`
- `reverseButtons()`
- `withOptions([...])` — any raw SweetAlert2 option

```php
LivewireAlert::title('Custom')
    ->success()
    ->withOptions([
        'width' => '400px',
        'background' => '#18181b',
        'allowOutsideClick' => false,
    ])
    ->show();
```

### Dependency injection

```php
use Jantinnerezo\LivewireAlert\LivewireAlert;

public function save(LivewireAlert $alert)
{
    $alert->title('Saved')->success()->show();
}
```

Same fluent API as the facade.

### Filament

In `AppServiceProvider::boot()`:

```php
use Filament\Support\Facades\FilamentAsset;
use Filament\Support\Assets\Js;
use Illuminate\Support\Facades\Vite;

FilamentAsset::register([
    Js::make('sweetalert2', Vite::asset('resources/js/sweetalert2.js')),
]);
```

## Gotchas

- `show()` is required. Builder methods alone do nothing.
- `update()` only swaps visual options — inputs and `didOpen` callbacks are not re-applied.
- Button event handlers run server-side via Livewire. The alert stays open until the request returns.
- `Position` enum is at `Jantinnerezo\LivewireAlert\Enums\Position`. String values also work.
- Flash alerts must be read in `mount()` of the destination component.

## Links

- Repo: https://github.com/jantinnerezo/livewire-alert
- SweetAlert2 options: https://sweetalert2.github.io/#configuration