Toast
Brief notifications stacked bottom right, wrapping the Base UI Toast. Announced politely to screen readers, expandable on hover, dismissible by swipe, timer paused while you're reading. Fire them from anywhere with one hook.
Setup
Two pieces, mounted once and before anything fires: the provider holds the queue, the Toaster renders the stack. This site does it in the root layout:
import { ToastProvider, Toaster } from "@usebones/react";
<ToastProvider>
{children}
<Toaster />
</ToastProvider>Playground
Every control maps to an option of toast.add. The demo mounts its own provider, so the position control moves only these toasts.
Variants
Default plus the four conventional types, each tinted with an icon, and a promise toast that follows an async call through loading, success, or failure with the types set automatically.
Recipes
The queue is plain data, so the common patterns are each a few lines: pick a corner, mix short and tall toasts, collapse repeats, and offer an undo.
Position. The Toaster takes a position: any corner or edge center, bottom right by default. Top positions peek downward and swipe upward.
Varying heights. Each toast's height is measured, so the stack and the expanded fan stay correct with mixed content lengths.
Deduplication. Pass a fixed id and repeat events collapse into one toast instead of stacking; each add refreshes the timer.
Undo action. The classic use of actionProps: the action closes the toast and a follow-up confirms.
Styling states
Each toast carries data-type with whatever type you pass (success, info, warning, and error come tinted with icons; anything else is yours to style), data-expanded while the stack is fanned out, and the usual data-starting-style/data-ending-style transitions:
.ub-toast[data-type="deploy"] .ub-toast-title {
color: var(--ub-accent);
}Props
The provider takes the queue-wide settings; everything per-toast goes to toast.add (or update/promise). The essentials:
| Prop | Type | Default | Description |
|---|---|---|---|
ToastProvider.timeout | number | 5000 | Milliseconds before auto-dismiss; paused on hover and focus. |
ToastProvider.limit | number | 3 | Most toasts shown at once; extras queue up. |
Toaster.position | ToasterPosition | "bottom-right" | Any corner or edge center; swipe direction follows. |
toast.add({ title }) | ReactNode | – | What the toast says; names it for screen readers. |
toast.add({ description }) | ReactNode | – | Supporting text under the title. |
toast.add({ type }) | string | – | Free-form tag surfaced as data-type for styling. |
toast.add({ actionProps }) | button props | – | Renders an action button; children is its label, onClick its handler. |
toast.promise(p, { loading, success, error }) | function | – | One toast that follows a promise through its three outcomes. |
Agent instructions
Working with a coding agent? Paste this into its context, or point it at llms.txt for the whole library.
ToastProvider, Toaster, useToast, from @usebones/react.
- Mount once: ToastProvider wrapping the app with one <Toaster /> inside (this renders the bottom-right stack; no toast markup anywhere else).
- Fire from any client component: const toast = useToast(); toast.add({ title, description, type, actionProps: { children, onClick } }). Returns an id for toast.update/toast.close.
- toast.promise(promise, { loading: {...}, success: {...}, error: {...} }) follows a promise through its outcomes.
- Provider settings: timeout (5000ms, paused on hover/focus), limit (3).
- Never mount a second Toaster; one provider and one stack per app.
- Restyle in CSS via .ub-toast, .ub-toast-title, .ub-toast-description, .ub-toast-action, [data-type="..."], [data-expanded], [data-starting-style]/[data-ending-style]. Tokens only.