Rewrote all the docs - more noob friendly now.
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
+39
-72
@@ -1,104 +1,73 @@
|
||||
# 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.
|
||||
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".
|
||||
|
||||
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.
|
||||
Unlike most components, toasts are triggered from **JavaScript**, not from the server-rendered template.
|
||||
|
||||
---
|
||||
|
||||
## 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`)
|
||||
## Quick example
|
||||
|
||||
```js
|
||||
window.showToast({
|
||||
title: "Operation complete", // required
|
||||
description: "All items saved.", // optional
|
||||
variant: "success", // "default" | "destructive" | "success"
|
||||
duration: 4000 // milliseconds before auto-dismiss
|
||||
title: "Saved!",
|
||||
variant: "success",
|
||||
duration: 3000
|
||||
});
|
||||
```
|
||||
|
||||
**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
|
||||
## All the options
|
||||
|
||||
```csharp
|
||||
public Toast(
|
||||
string title,
|
||||
string description = "",
|
||||
string variant = "default")
|
||||
```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)
|
||||
})
|
||||
```
|
||||
|
||||
The constructor builds a static initial toast element. Most use-cases call `window.showToast(...)` from JS instead.
|
||||
|
||||
| Parameter | Description |
|
||||
| Option | What it does |
|
||||
|---|---|
|
||||
| `title` | Required notification heading |
|
||||
| `description` | Optional body text |
|
||||
| `variant` | `"default"` / `"destructive"` / `"success"` |
|
||||
| `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. |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
## Real-world examples
|
||||
|
||||
### Trigger from JavaScript after an HTMX event
|
||||
### Show a toast after an HTMX request completes
|
||||
|
||||
```js
|
||||
document.body.addEventListener('htmx:afterRequest', function (e) {
|
||||
if (e.detail.successful) {
|
||||
window.showToast({ title: 'Saved', variant: 'success', duration: 3000 });
|
||||
window.showToast({ title: 'Changes saved', variant: 'success', duration: 3000 });
|
||||
} else {
|
||||
window.showToast({ title: 'Error', description: 'Could not save.', variant: 'destructive' });
|
||||
window.showToast({ title: 'Something went wrong', description: 'Please try again.', variant: 'destructive' });
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Trigger from a server response header
|
||||
### Trigger from the server via a response header
|
||||
|
||||
Add a response header `HX-Trigger` in your handler:
|
||||
Add an `HX-Trigger` response header in your handler to fire a custom event:
|
||||
|
||||
```csharp
|
||||
ctx.Response.Headers.Append("HX-Trigger",
|
||||
"""{"showToast":{"title":"Saved!","variant":"success","duration":3000}}""");
|
||||
"""{
|
||||
"showToast": {
|
||||
"title": "Profile updated",
|
||||
"variant": "success",
|
||||
"duration": 3000
|
||||
}
|
||||
}""");
|
||||
```
|
||||
|
||||
Client-side listener:
|
||||
Then listen for it on the client:
|
||||
|
||||
```js
|
||||
document.body.addEventListener('showToast', function (e) {
|
||||
@@ -106,17 +75,15 @@ document.body.addEventListener('showToast', function (e) {
|
||||
});
|
||||
```
|
||||
|
||||
### 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());
|
||||
```
|
||||
This is the cleanest pattern for server-triggered toasts — the server decides the message and variant, the client handles the display.
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user