Toast

v1.1.2

Documentation Under Review

The Toast component provides a flexible notification system for displaying temporary messages to users in product interfaces. Built on the Sonner library, it offers smooth animations, automatic queuing, and customizable styling across five semantic variants.

Installation

Install the Toast component from the Catalyst component library:

npm install @pmi/catalyst-toast

Usage

import {
  ToastProvider,
  ToastContent,
  ToastTitle,
  ToastDescription,
  ToastIcon,
  ToastAction,
  ToastDismiss,
  renderToastRoot
} from '@pmi/catalyst-toast'

Key Features

• Five Variants: General, brand, warning, success, and danger styles
• Imperative API: Programmatically trigger toasts with renderToastRoot()
• Auto-dismiss: Configurable duration with automatic removal
• Manual Dismiss: Close button with accessible interaction
• Action Buttons: Integrated call-to-action with auto-dismiss
• Icon Support: Flexible icon positioning and theming
• Custom Styling: Override default styles with custom variants
• Dark Mode: Full dark mode support with semantic colors
• Accessibility: WCAG 2.1 AA compliant with keyboard support
• Toast Queue: Automatic stacking with Sonner's queue management

Examples

Default Toast

The basic toast with title, description, icon, and action button.

Toast Variants

Five semantic variants for different notification types.

Expanded Mode

Display toasts in an always-visible expanded mode for demonstration purposes.

Non-Catalyst Action Button

Example using native button element instead of Catalyst Button component.

Custom Styled Toasts

Examples demonstrating custom styling using CVA (class-variance-authority) patterns.

Common Use Cases

Real-world examples demonstrating practical toast implementations.

Form Success Confirmation

Display success feedback after form submission with action to view results.

Session Warning

Warning toast with extended duration for important time-sensitive messages.

Duration Guidelines

Recommended auto-dismiss durations for different use cases:

Component API

ToastProvider

The root provider component that manages toast rendering and configuration.

ToastContent

The main container for toast content with variant styling.

ToastTitle

The title heading for the toast message.

ToastDescription

The description text for the toast message.

ToastIcon

Container for the toast icon with variant-aware styling.

ToastAction

Action button within the toast that auto-dismisses on click.

ToastDismiss

Close button to manually dismiss the toast.

renderToastRoot

Imperative function to programmatically render toasts.

renderToastRoot(
  children: React.ReactNode,
  props: ToastRootProps
): string | number

Parameters:

• children: The toast content (ToastContent with all sub-components)
• props: Configuration object
  • id: Unique toast identifier
  • duration: Auto-dismiss duration in milliseconds (default: 5000)
  • unstyled: Remove default Sonner styling (automatically set to true)
  • Additional Sonner API options

Returns: The toast ID

Usage Guidelines

Composition Pattern

Toasts use a compound component pattern. Always compose them in this order:

1. ToastProvider - Wraps the trigger and manages toast queue
2. ToastContent - Main container with variant
3. ToastDismiss - Close button (positioned absolutely)
4. ToastIcon - Icon container
5. Text container (<div className="w-full">)
   • ToastTitle - Title text
   • ToastDescription - Description text
6. ToastAction - Action button

Toast IDs

Generate unique IDs for each toast instance:

const id = `toast-${Date.now()}`
// or
const id = useId()

Pass the same ID to ToastContent, ToastAction, and ToastDismiss.

Auto-dismiss Duration

Configure duration in the renderToastRoot options:

renderToastRoot(content, { id, duration: 5000 }) // 5 seconds

Variant Prop Threading

Pass the same variant prop to all sub-components for consistent theming:

<ToastContent variant="success">
  <ToastIcon variant="success">...</ToastIcon>
  <ToastTitle variant="success">...</ToastTitle>
  <ToastDescription variant="success">...</ToastDescription>
  <ToastAction variant="success">...</ToastAction>
  <ToastDismiss variant="success">...</ToastDismiss>
</ToastContent>

Custom Styling

Override default styles by passing custom classes to sub-components. Use cn() utility to merge classes:

import { cn } from '@pmi/catalyst-utils'

<ToastContent
  variant="general"
  className={cn(
    'bg-custom-100 dark:bg-custom-800',
    'border-custom-200 dark:border-custom-700'
  )}
>
  {/* ... */}
</ToastContent>

Action Button Options

Two ways to render action buttons:

1. Using asChild (Recommended):

<ToastAction asChild id={id} variant="general">
  <Button size="sm">Action</Button>
</ToastAction>

2. Native Button:

<ToastAction
  id={id}
  variant="general"
  label="Action Text"
  className="custom-button-styles"
/>

Accessibility

• Always provide aria-label on dismiss buttons
• Use semantic variants that match message intent
• Toasts automatically receive focus management
• Keyboard navigation is handled by Sonner

Best Practices

• Keep messages concise - Toasts auto-dismiss, so content should be scannable
• Use appropriate variants - Match semantic meaning (success for confirmations, danger for errors)
• Provide actions sparingly - Only include actions when truly needed
• Test timing - Ensure duration allows users to read and act
• Avoid overuse - Too many toasts can be disruptive
• Product-specific styling - Use custom styling to match your product's design system

Related Components

• Alert - Static notification messages
• Button - Used for actions and dismiss
• Dialog - For more complex interactions

Accessibility

The Toast component follows WCAG 2.1 Level AA guidelines:

• Keyboard Navigation: Full keyboard support for actions and dismiss
• Focus Management: Automatic focus handling with visible indicators
• ARIA Labels: Proper labeling for screen readers
• Color Contrast: All variants meet contrast requirements
• Motion: Respects user's reduced motion preferences
• Timing: Configurable duration for different reading speeds