# Toast

A small pop-up notification that appears in the corner of the screen, stays briefly, and then fades out on its own. Use it to give users confirmation after an action — "Saved!", "Error: could not connect", "Profile updated".

Unlike most components, toasts are triggered from **JavaScript**, not from the server-rendered template.

---

## Quick example

```js
window.showToast({
    title:   "Saved!",
    variant: "success",
    duration: 3000
});
```

---

## All the options

```js
window.showToast({
    title:       string,   // required
    description: string,   // optional — shown below the title
    variant:     string,   // "default" | "destructive" | "success"
    duration:    number    // milliseconds before auto-dismiss (default: 4000)
})
```

| Option | What it does |
|---|---|
| `title` | The main notification text. |
| `description` | Optional secondary text below the title. |
| `variant` | `"default"` = neutral; `"destructive"` = red border (errors); `"success"` = green border. |
| `duration` | How long the toast stays visible before fading out. |

---

## Real-world examples

### Show a toast after an HTMX request completes

```js
document.body.addEventListener('htmx:afterRequest', function (e) {
    if (e.detail.successful) {
        window.showToast({ title: 'Changes saved', variant: 'success', duration: 3000 });
    } else {
        window.showToast({ title: 'Something went wrong', description: 'Please try again.', variant: 'destructive' });
    }
});
```

### Trigger from the server via a response header

Add an `HX-Trigger` response header in your handler to fire a custom event:

```csharp
ctx.Response.Headers.Append("HX-Trigger",
    """{
        "showToast": {
            "title": "Profile updated",
            "variant": "success",
            "duration": 3000
        }
    }""");
```

Then listen for it on the client:

```js
document.body.addEventListener('showToast', function (e) {
    window.showToast(e.detail);
});
```

This is the cleanest pattern for server-triggered toasts — the server decides the message and variant, the client handles the display.

---

## How it works

`window.showToast` creates a new `<div>` with the toast content and appends it to the `ToastViewport` container. A CSS animation slides it in. After `duration` ms, a fade-out animation plays and then the element is removed from the DOM. The dismiss button (×) triggers the same fade-out immediately.

You must have a `ToastViewport` component in your layout for toasts to appear. See [ToastViewport.md](./ToastViewport.md).

- Always place a single `ToastViewport` in your main layout so toasts have a container to render into. See [ToastViewport.md](ToastViewport.md).
- Use the `HX-Trigger` header pattern to trigger toasts from HTMX responses — it keeps toast logic on the server without requiring extra HTMX endpoints.
- `duration: 0` means the toast never auto-dismisses — the user must click the × button.
- Multiple toasts stack upward in the viewport (new ones appear above older ones) due to `flex-col-reverse` in `ToastViewport`.
- For progress toasts that update as a background job runs, call `showToast` once and then use a reference to the element to update the description text.
- For progress toasts that update as a background job runs, call `showToast` once and then use a reference to the element to update the description text.

---

## Complete page example

**`Templates/ContactFormPage.htmx`**
```html
<div class="max-w-lg mx-auto py-10">
  <h1 class="text-2xl font-bold mb-6">Contact us</h1>
  <form hx-post="/contact"
        hx-target="this"
        hx-swap="outerHTML">
    $$AntiforgeryToken$$
    <div class="space-y-4 mb-6">
      $$NameInput$$
      $$EmailInput$$
      $$MessageArea$$
    </div>
    $$SubmitBtn$$
  </form>
</div>
```

**`Templates/ContactFormPage.htmx.cs`**
```csharp
namespace Htmx.ApiDemo.Templates;

public sealed class ContactFormPage : ContactFormPageBase
{
    private readonly IHtmxComponent _name;
    private readonly IHtmxComponent _email;
    private readonly IHtmxComponent _message;
    private readonly IHtmxComponent _submit;
    private readonly byte[] _afToken;

    public ContactFormPage(IAntiforgery af, HttpContext ctx)
    {
        var tokens = af.GetAndStoreTokens(ctx);
        _afToken = $"""<input type="hidden" name="{tokens.FormFieldName}" value="{tokens.RequestToken}">""".ToUtf8Bytes();

        _name    = new Components.Input(id: "name",    name: "name",    label: "Name",    placeholder: "Jane Smith");
        _email   = new Components.Input(id: "email",   name: "email",   label: "Email",   placeholder: "jane@example.com", type: "email");
        _message = new Components.Textarea(id: "message", name: "message", label: "Message", rows: 4);
        _submit  = new Components.Button("Send message", type: "submit");
    }

    protected override void RenderAntiforgeryToken(HtmxRenderContext ctx) => ctx.Writer.WriteUtf8(_afToken);
    protected override void RenderNameInput(HtmxRenderContext ctx)        => _name.Render(ctx.Next());
    protected override void RenderEmailInput(HtmxRenderContext ctx)       => _email.Render(ctx.Next());
    protected override void RenderMessageArea(HtmxRenderContext ctx)      => _message.Render(ctx.Next());
    protected override void RenderSubmitBtn(HtmxRenderContext ctx)        => _submit.Render(ctx.Next());
}
```

**POST handler — triggers a toast via `HX-Trigger`**
```csharp
[Handler]
[MapPost("/contact")]
public static partial class PostContactHandler
{
    public record Command(
        [property: FromForm] string Name,
        [property: FromForm] string Email,
        [property: FromForm] string Message);

    private static Task<IResult> HandleAsync(
        [AsParameters] Command cmd, HttpContext ctx, IAntiforgery af, CancellationToken ct)
    {
        // Persist / send message…

        // Re-render empty form so user can send another message
        var buf = new System.Buffers.ArrayBufferWriter<byte>();
        new ContactFormPage(af, ctx).Render(new HtmxRenderContext(buf));

        ctx.Response.Headers["HX-Trigger"] = """{"showToast":{"title":"Message sent!","description":"We'll get back to you soon."}}""";
        return Task.FromResult(Results.Content(
            System.Text.Encoding.UTF8.GetString(buf.WrittenSpan), "text/html"));
    }
}
```

> **Tip**: The `HX-Trigger` header fires the `showToast` custom event that the `<toast-viewport>` element listens for (see `ToastViewport`).

**`AppJsonSerializerContext.cs`**
```csharp
[JsonSerializable(typeof(PostContactHandler.Command), TypeInfoPropertyName = "ContactCommand")]
```