@@ -0,0 +1,213 @@
|
||||
# Toast
|
||||
|
||||
A transient notification that appears in the bottom-right corner (or wherever `ToastViewport` is placed), auto-dismisses after a configurable duration, and can be dismissed manually.
|
||||
|
||||
Toasts are triggered **client-side** via `window.showToast(...)` from JavaScript — they are not server-rendered components like most others. The `Toast` component class produces the initial toast markup for use as a static template or in the ToastViewport; in practice most toasts are created dynamically by the JS API.
|
||||
|
||||
---
|
||||
|
||||
## HTML structure (dynamically created by JS)
|
||||
|
||||
```
|
||||
div.toast[role=alert, aria-live=polite, data-variant]
|
||||
div.flex.items-start.gap-3
|
||||
div.flex-1
|
||||
p.font-medium.text-sm ← title
|
||||
p.text-sm.text-muted-foreground ← description (omitted when empty)
|
||||
button.ml-auto[aria-label=Dismiss] ← × close button
|
||||
svg (×)
|
||||
```
|
||||
|
||||
The outer `div.toast` is appended to the `ToastViewport` container by JS and removed after `duration` ms.
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `toast` | Defined in `input.css`: `w-80 rounded-lg border bg-background p-4 shadow-lg pointer-events-auto` |
|
||||
| `toast-enter` / `toast-exit` | CSS keyframe animation classes applied by JS for slide-in/fade-out |
|
||||
| `data-variant="default"` | Border `border-border` |
|
||||
| `data-variant="destructive"` | Border `border-destructive`, title `text-destructive` |
|
||||
| `data-variant="success"` | Border `border-green-500` |
|
||||
|
||||
---
|
||||
|
||||
## JavaScript (`showToast` in `components.js`)
|
||||
|
||||
```js
|
||||
window.showToast({
|
||||
title: "Operation complete", // required
|
||||
description: "All items saved.", // optional
|
||||
variant: "success", // "default" | "destructive" | "success"
|
||||
duration: 4000 // milliseconds before auto-dismiss
|
||||
});
|
||||
```
|
||||
|
||||
**Implementation steps:**
|
||||
|
||||
1. Build the toast `div` element with the classes and markup described above
|
||||
2. Apply `toast-enter` class → CSS slide-in animation plays
|
||||
3. Append to the `ToastViewport` (`#toast-viewport` by default, or the first `.toast-viewport` found)
|
||||
4. After `duration` ms, apply `toast-exit` class → CSS fade-out animation plays
|
||||
5. After fade-out completes, remove the element from the DOM
|
||||
6. Dismiss button click runs the same fade-out + remove cycle immediately
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
|
||||
```csharp
|
||||
public Toast(
|
||||
string title,
|
||||
string description = "",
|
||||
string variant = "default")
|
||||
```
|
||||
|
||||
The constructor builds a static initial toast element. Most use-cases call `window.showToast(...)` from JS instead.
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `title` | Required notification heading |
|
||||
| `description` | Optional body text |
|
||||
| `variant` | `"default"` / `"destructive"` / `"success"` |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
|
||||
### Trigger from JavaScript after an HTMX event
|
||||
|
||||
```js
|
||||
document.body.addEventListener('htmx:afterRequest', function (e) {
|
||||
if (e.detail.successful) {
|
||||
window.showToast({ title: 'Saved', variant: 'success', duration: 3000 });
|
||||
} else {
|
||||
window.showToast({ title: 'Error', description: 'Could not save.', variant: 'destructive' });
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Trigger from a server response header
|
||||
|
||||
Add a response header `HX-Trigger` in your handler:
|
||||
|
||||
```csharp
|
||||
ctx.Response.Headers.Append("HX-Trigger",
|
||||
"""{"showToast":{"title":"Saved!","variant":"success","duration":3000}}""");
|
||||
```
|
||||
|
||||
Client-side listener:
|
||||
|
||||
```js
|
||||
document.body.addEventListener('showToast', function (e) {
|
||||
window.showToast(e.detail);
|
||||
});
|
||||
```
|
||||
|
||||
### Server-rendered initial toast (rare)
|
||||
|
||||
```csharp
|
||||
// Used as a slot inside a page that always shows a greeting on first load:
|
||||
protected override void RenderWelcomeToast(HtmxRenderContext ctx)
|
||||
=> new Toast("Welcome back!", "Your dashboard is ready.", "success").Render(ctx.Next());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- 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")]
|
||||
```
|
||||
Reference in New Issue
Block a user