Toast
Says, briefly, what just happened (“Changes saved”), then leaves on its own. For anything the reader must act on or must not miss, use a Notification, which stays.
Live preview
Rendered by the component itself from the same generated tokens as the rest of the site.
// Once, around the app:
<ToastProvider>{children}</ToastProvider>
// Anywhere under it:
const toast = useToast()
toast({
variant: 'success',
title: 'Changes saved',
body: 'Your theme is live for everyone.',
timestamp: 'Time stamp [12:04:31]',
})Installation
Install it with the shadcn CLI, along with everything it uses. New project? Set it up first, as Quick start shows.
npx shadcn@latest add https://www.graphite-ui.com/r/toast.jsonimport { ToastProvider, useToast } from '@/components/ui/toast'Anatomy
The status icon and the stripe in the status colour; the title over the message; a time stamp, or an action, under them; and the close at the top right. It arrives at the top right of the window over everything else, with the overlay shadow.
- IconRequiredThe status icon, Notification's (Failed and Succeeded at 16, the warning triangle and fi-rs-info at 20), 14 in from the left and the top.
- TitleRequiredTitle/5 SemiBold, over the message.
- MessageOptionalBody/3.
- Time stampOptionalThe kit's Time text, Body/3, 24 under the message. Not drawn with an action, as the kit draws it.
- ActionOptionalThe kit's Actionable, a small ghost Button 24 under the message.
- CloseOptionalThe kit's Close, a 48px ghost icon-only Button flush in the top right, named "Dismiss notification".
Variants
Status sets the colours and the icon, as Notification’s does. High contrast inverts the fill. Actionable puts a small button where the time stamp would be.
API reference
Generated from the contract, versioned with it, and checked by drift-check. This table cannot describe props the component does not have.
| Prop | Type | Default | Notes |
|---|---|---|---|
| variant | 'info' | 'success' | 'warning' | 'danger' | — | The kit's Status. Its Error is danger here, as in Notification. |
| highContrast | boolean | — | The kit's High contrast. Off by default, as Notification's is; the kit's Toast set defaults it on. |
| title / body / timestamp | — | — | The kit's Title text, Message text and Time text. |
| action | { label: string; onClick: () => void } | — | |
| onClose | () => void | — | |
| duration | — | — | Given when the toast is shown through the host. 6000 ms by default; danger toasts stay until closed unless a duration is given. The countdown holds while the pointer or focus is on the toast and resumes where it stopped. |
Design tokens
Every swatch is live. Change the source color in the header and this table repaints, because it reads the same roles the component does.
on-surfaceTitle, message and time stamp on every status container (Notification's D6 sweep covers it).infoIcon and stripe on the info variant.successIcon and stripe on the success variant.warningIcon and stripe on the warning variant. The triangle and its "!" at rest are drawn by Notification's status icon.dangerIcon and stripe on the danger variant.info-containerFill on the info variant; its stripe and icon in high contrast.success-containerFill on the success variant; its stripe and icon in high contrast.warning-containerFill on the warning variant; its stripe, icon and triangle in high contrast.danger-containerFill on the danger variant; its stripe and icon in high contrast.on-warning-containerThe "!" on the warning triangle in high contrast.on-backgroundThe high-contrast fill.backgroundHigh-contrast text and close glyph.primary-containerThe action label in high contrast, Notification's stand-in for the kit's inverse link.shadowThe overlay shadow (the kit's DROP_SHADOW 0 2 6).motionThe arrival, a short fade and drop, none under reduced motion.textTitle/5 SemiBold and Body/3.spacingThe 14 inset and icon gap, the 24 gap, the padding and the host's placement.radiusSquare corners.
Usage
The contract's prohibitions, written as the choices you will actually face.
Do
- Confirm something the reader just did, in a few words.
- Offer Undo as the action where an action can be undone.
- Let errors stay until they are closed; they do by default.
- Show one at a time where you can. They stack, but a pile is noise.
Don’t
- Put the only route to something in a toast. It leaves.
- Use a toast for a problem on the page. Put a Notification next to it.
- Shorten the duration below what it takes to read.
- Show a toast for something the reader can already see happen.
Accessibility
What the component does for you, and what it leaves to you.
- Live region
- The host is a polite live region named “Notifications”, so each toast is announced as it arrives. An error is an
alertand interrupts. - Timing
- Six seconds by default. The countdown holds while the pointer or keyboard focus is on the toast, and resumes where it stopped. Errors stay until closed.
- Close
- A button named “Dismiss notification”. The action and close are reachable with Tab, as anything else on the page.
- Contrast
- Text is on-surface on every status container, Notification’s swept pairs; high contrast is background on on-background.
Figma parity
The kit’s Toast is one set on the Notification page, Notification - Toast. The code is Toast, drawn, and a host that times and stacks it.
| Kit axis | Values | Code | How it maps |
|---|---|---|---|
| Status | Info · Success · Warning · Error | variant | info, success, warning and danger, as Notification. |
| High contrast | False · True | highContrast | The kit’s set defaults it on; the code keeps Notification’s default, off. |
| Actionable | False · True | action | The action takes the time stamp’s place, as the kit draws it. |
| Time text | Text | timestamp | Body/3, 24 under the message. |
| Close | Boolean | onClose | The host always passes it, so every shown toast can be closed. |
| Timing | — | duration | The kit has none; this is the code’s, and the contract’s. |