Skip to content
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/toast

Or 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

Toast props
PropTypeDefaultDescription
useToast().title (required)ReactNode—What happened, in a few words.
useToast().descriptionReactNode—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().timeoutnumber6000 (errors: 0)ms before auto-dismiss.
Toaster.limitnumber3Toasts shown at once.

Accessibility

Keyboard
KeyAction
F6Moves focus into the toast region
TabMoves 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