Wave 2
Toast
Brief feedback after an action, announced without moving focus.
- Errors tied to a field: use FieldError.
- Persistent page status: use Alert.
- Anything that needs a decision: use Dialog.
Install
Terminal
pnpm dlx shadcn@latest add @acme/toastOr import from the package: import { Toaster } from '@acme/react'
Examples
Basic
toast-basic.tsx
'use client'
import { Button } from '@/components/ui/button'
import { Toaster, useToast } from '@/components/ui/toast'
function Actions() {
const toast = useToast()
return (
<div className="flex flex-wrap gap-3">
<Button
variant="outline"
onClick={() =>
toast({
title: 'Invoice sent',
description: 'Northwind Traders will get it in a few minutes.',
type: 'success',
action: { label: 'Undo', onClick: () => {} },
})
}
>
Send invoice
</Button>
<Button
variant="outline"
onClick={() =>
toast({
title: 'Couldn’t save draft',
description: 'Check your connection and try again.',
type: 'error',
})
}
>
Trigger an error
</Button>
</div>
)
}
export default function ToastBasic() {
return (
<Toaster>
<Actions />
</Toaster>
)
}Props
| Prop | Type | Default | Description |
|---|---|---|---|
| useToast().title (required) | ReactNode | — | What happened, in a few words. |
| useToast().description | ReactNode | — | Optional detail. |
| useToast().type | 'info' | 'success' | 'warning' | 'error' | 'info' | Sets the icon and urgency. Errors are announced assertively and stay until dismissed. |
| useToast().action | { label, onClick } | — | An Undo or follow-up action. |
| useToast().timeout | number | 6000 (errors: 0) | ms before auto-dismiss. |
| Toaster.limit | number | 3 | Toasts shown at once. |
Accessibility
| Key | Action |
|---|---|
| F6 | Moves focus into the toast region |
| Tab | Moves to the action and dismiss buttons |
- Role
- status (polite) / alert (error)
- You provide
- Wrap the app in <Toaster> once.
- Built in
- Announced via a live region without stealing focus (WCAG 4.1.3).
- Errors never auto-dismiss; others stay 6 seconds (WCAG 2.2.1: important messages must not vanish on a timer).
- Every toast has an icon, so type is not color alone.
- WCAG 2.2 criteria
- 1.4.1, 2.2.1, 4.1.3
Don’t
- Show more than one toast for one action.
- Put the only copy of important information in a toast.
Tokens
- color.popover
- color.success
- color.warning
- color.destructive
- color.info
- elevation.4
- z.toast