App components / Alerts & toasts
Toast
A short message that floats in after something happens: a rim around the message card, its action on the tray below. Call toast() from anywhere; toast.undo() and toast.progress() give the one-line Undo toast and the upload tracker in the same pile. New toasts pile up in front of older ones; hover or tab into the pile and it fans out, pausing every timer.
Code
The component itself, ready to drop into your project. Switch between React, Vue and plain HTML; every version uses the same Tailwind classes on Ochre's tokens.
Installation
Examples
Leading and action
Lead with an icon, an avatar or a date tile; put the action as a link in the card, as a footer on the tray, or leave it out.
Undo toast
One line and Undo, in ink or on the tray. Press ⌘Z while it shows to undo.
Progress toast
The percentage climbs, then the same toast finishes or fails with Try again.
Undo action
A full toast with Undo on the tray. It closes the toast after it runs.
Loading, then done
Start with toast.loading and update the same id when the work finishes.
Tones
Neutral has no icon; the others carry their status colour on the icon only.
Motion
Built on Ochre's ease-out curves. With reduced motion switched on, everything still works, it just doesn't move.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
| toast(options) | (options: ToastOptions) => string | – | Shows a toast and returns its id. Pass the same id again to update it. |
| toast.success / error / loading | (title, options?) => string | – | Shorthands that set the tone. |
| toast.undo | (title, { onUndo, variant?, label? }) => string | – | Undo toast: one line and Undo with its shortcut. ⌘Z or Ctrl+Z runs the newest one unless the person is typing. |
| toast.progress | (options & { progress: number }) => string | – | Progress toast: meta heads the tray, the bar fills the card. Update it by id; state done or failed finishes it. |
| toast.dismiss | (id?: string) => void | – | Closes one toast, or every toast without an id. |
| title | ReactNode | – | What happened, in a few words: 3 issues archived. |
| description | ReactNode | – | Optional second line in the muted colour. |
| tone | "neutral" | "success" | "warning" | "danger" | "loading" | "neutral" | Icon on the card. Loading stays until it's updated or dismissed. |
| icon / avatar / date | ReactNode / { name, src? } / Date | { month, day } | – | Leading: your own icon (the tone's icon by default), a person's avatar, or a date tile for meetings and deadlines. |
| action | { label: string; onClick: () => void } | – | One button on the tray, such as Undo. The toast closes after it runs, unless the action updated the same toast. |
| link | { label: string; href?: string; onClick?: () => void } | – | Action Link: an accent link inside the card, under the detail. |
| footer | { label: string; icon?: ReactNode; onClick: () => void } | – | Action Footer: one centred accent action across the tray, in place of the button row. |
| dismissible | boolean | true | False hides Dismiss. With no meta, action or footer, the toast is just the rim around its card (Action None). |
| variant | "ink" | "tray" | "ink" | Undo toast only: the ink pill or the tray. |
| progress / state | number / "running" | "done" | "failed" | "running" | Progress toast: 0 to 100. Running and failed stay until they change; done closes after 5 seconds. |
| meta | ReactNode | – | Mono line on the tray, left of the buttons: a time, count or id. |
| duration | number | 5000 | Milliseconds before it closes; 8000 with an action. Infinity keeps it open. |
| <Toaster position max> | "bottom-right" | "bottom-left" | "top-right", number | "bottom-right", 5 | Mount once near the root of the app. Three show in the pile; up to max are kept. |
Usage
Use it for
- Confirming an action the person just took, ideally with Undo: archived, moved, sent.
- Long tasks that finish in the background: show loading, then update the same toast.
- Uploads and exports with a percentage: toast.progress, updated by id until done or failed.
- A person or a meeting: lead with their avatar or a date tile, and put View or Join call in the card or the footer.
Avoid
- Errors the person must fix before carrying on: put an Alert or a Field error where the problem is.
- Toasts for things the page already shows.
- More than one action. Undo or View is enough.