Toast

Toast displays temporary feedback in response to user actions. It appears at the corner of the screen and auto-dismisses after a set time — triggered easily with the imperative API (toast.success(), etc.) from anywhere.

Design spec: Toast width is fixed at360px. On screens narrower than 360px, it auto-scales withmax-width: calc(100vw - 48px).

Types

Positions

Promise

Async Support

Pure

React

Playground

Preview

defaultbottom-right

Type

Position

Options

toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00 PM',
})

Types

Features

Action & Cancel

actioncancelAdd inline buttons with the action and cancel options.

toast('File deleted', {
  action: { label: 'Undo', onClick: () => handleUndo() },
  cancel: { label: 'Dismiss', onClick: () => {} },
})

Promise

toast.promise()toast.promise() auto-transitions loading → success/error for async operations.

toast.promise(
  fetch('/api/save'),
  {
    loading: 'Saving...',
    success: 'Saved!',
    error: 'Failed to save',
  }
)

Close Button

closeButtonShow a close button on a toast with closeButton.

toast.info('Notification', {
  closeButton: true,
  description: 'You have 3 unread messages.',
})

Rich Colors

richColorsSetting richColors on Toaster emphasizes status toasts with a solid background.

<Toaster richColors />

toast.success('Saved!')  // solid green background
toast.error('Failed!')   // solid red background

Loading

toast.loading()stays visible with a spinner until manually closed or dismissed withtoast.dismiss(id).

const id = toast.loading('Processing...')
// Later:
toast.dismiss(id)

API

Component Structure

Toast— Pure React (Imperative API)

toast()Propstoast.success()toast.error()toast.warning()toast.info()toast.loading()toast.promise()toast.custom()toast.dismiss()<Toaster />Props

toast(message, options?)PropsDefault toast

toast.success(message, options?)Success toast

toast.error(message, options?)Error toast

toast.warning(message, options?)Warning toast

toast.info(message, options?)Info toast

toast.loading(message, options?)Loading toast (persistent)

toast.promise(promise, handlers)Promise-linked toast

toast.custom(render, options?)Custom JSX toast

toast.dismiss(id?)Close toast (omit id to close all)

<Toaster />PropsRendering provider

Props

Toaster

position"bottom-right"

Toast display position

duration4000

number

Auto-dismiss delay in ms — 0 for persistent

visibleToasts5

number

Maximum number of toasts shown at once

closeButtonfalse

boolean

Show a close button on all toasts

richColorstrue

boolean

Emphasize status colors with solid backgrounds — false for tint

expandfalse

boolean

Always expand all toasts

offset24

number

Offset from the screen edge (px)

gap8

number

Gap between toasts (px)

size"default"

"sm" | "default" | "lg"

Toast size

classNameundefined

string

Additional CSS class for the container

Name	Type	Default	Description
`position`	`"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"`	`"bottom-right"`	Toast display position
`duration`	`number`	`4000`	Auto-dismiss delay in ms — 0 for persistent
`visibleToasts`	`number`	`5`	Maximum number of toasts shown at once
`closeButton`	`boolean`	`false`	Show a close button on all toasts
`richColors`	`boolean`	`true`	Emphasize status colors with solid backgrounds — false for tint
`expand`	`boolean`	`false`	Always expand all toasts
`offset`	`number`	`24`	Offset from the screen edge (px)
`gap`	`number`	`8`	Gap between toasts (px)
`size`	`"sm" \| "default" \| "lg"`	`"default"`	Toast size
`className`	`string`	`undefined`	Additional CSS class for the container

toast() Options

descriptionundefined

ReactNode

Supporting description text

duration4000

number

Per-toast auto-dismiss delay (ms)

dismissibletrue

boolean

Whether the toast can be dismissed

closeButtonfalse

boolean

Show a close button on this toast

iconauto (by type)

ReactNode

Custom icon

actionundefined

{ label: string; onClick: () => void }

Action button

cancelundefined

{ label: string; onClick: () => void }

Cancel button

onDismissundefined

(toast) => void

Callback when the toast is dismissed

onAutoCloseundefined

(toast) => void

Callback when auto-dismissed

idauto

string

Toast identifier for updates and dismiss

classNameundefined

string

Additional CSS class for this toast

Name	Type	Default	Description
`description`	`ReactNode`	`undefined`	Supporting description text
`duration`	`number`	`4000`	Per-toast auto-dismiss delay (ms)
`dismissible`	`boolean`	`true`	Whether the toast can be dismissed
`closeButton`	`boolean`	`false`	Show a close button on this toast
`icon`	`ReactNode`	`auto (by type)`	Custom icon
`action`	`{ label: string; onClick: () => void }`	`undefined`	Action button
`cancel`	`{ label: string; onClick: () => void }`	`undefined`	Cancel button
`onDismiss`	`(toast) => void`	`undefined`	Callback when the toast is dismissed
`onAutoClose`	`(toast) => void`	`undefined`	Callback when auto-dismissed
`id`	`string`	`auto`	Toast identifier for updates and dismiss
`className`	`string`	`undefined`	Additional CSS class for this toast

Code Recipes

Anatomy

Undo

Toast Root

Toast container

Icon

Status icon

Message

Main message

Description

Supporting description

Action

Action button

Close button

Best Practices

✓

Do

✓Use short, clear messages
✓Match the type to the status
✓Provide an Undo action for destructive operations

Don't

✕Don't put long text or forms inside a toast
✕For confirmation, use Modal/AlertModal instead
✕For persistent status, use Alert — Toast is temporary
✕Don't show too many toasts at once

Toast vs Alert

Both are used for user notifications, but differ in persistence and interaction.

Display

Toast: Temporary — disappears automatically

Alert: Fixed in page (persistent)

Trigger

Toast: After user action — as feedback

Alert: On page load or state change

Content

Toast: Short message (1–2 lines)

Alert: Title + description (rich)

Dismiss

Toast: Auto-dismissed (after a few seconds)

Alert: Manual (closable) or always shown

Use case

Toast: Save complete, copy complete, etc.

Alert: System state, warnings, errors

ARIA

Toast: role="status" + aria-live

Alert: role="alert" / role="status"

Feature	Toast	Alert
Display	Temporary — disappears automatically	Fixed in page (persistent)
Trigger	After user action	On page load or state change
Content	Short message	Title + description (rich)
Dismiss	Auto-dismissed (after a few seconds)	Manual (closable) or always shown
Use case	Save complete, copy complete	System state, warnings, errors
ARIA	role="status" + aria-live	role="alert" / role="status"

Key distinction: Use Toast for temporary feedback from user actions. Use Alert for persistent in-page status notifications.

Accessibility

ARIA / WCAG

role="alert" auto-applied on error/warning
role="status" for default/success/info/loading
aria-live="assertive" urgent notifications (error/warning)
aria-live="polite" general notifications (default/success/info/loading)
Container includes aria-label="Notifications"
Close button includes aria-label="Close"
Timer auto-pauses on hover

Toast

Playground

Types

Features

Action & Cancel

Promise

Close Button

Rich Colors

Loading

API

Component Structure

Props

Toaster

toast() Options

Code Recipes

Anatomy

Best Practices

Do

Don't

Toast vs Alert

Accessibility

ARIA / WCAG

Related

Alert

Modal

Badge

Spinner