Toast

v1.1.4

Documentation Under Review

Catalyst Toast provides a flexible notification system built on Sonner, adding design-token-matched variants, compound sub-components, and accessibility defaults so you can ship production-ready toast notifications without extra configuration.

Installation

npm install @pmi/catalyst-toast

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

Place ToastProvider once near the root of your app so the Sonner Toaster portal is available to every page. A Next.js root layout is a typical location:

// app/layout.tsx
import { ToastProvider } from '@pmi/catalyst-toast';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ToastProvider>
          {children}
        </ToastProvider>
      </body>
    </html>
  );
}

Variants

General

The default neutral style for informational messages.

Brand

PMI-branded violet style for product announcements and updates.

Warning

Caution style using yellow tones for non-critical alerts.

Success

Positive confirmation style using green tones.

Danger

Error or destructive-action style using red tones.

API Reference

Toast is a compound component. The sections below summarize the API surface for each part.

ToastProvider

Renders the Sonner Toaster portal. Mount it once at the app root (e.g. in your layout file) so every page can fire toasts via renderToastRoot. Also accepts all Sonner ToasterProps (e.g. position, expand, richColors, duration, theme) and the unstyled prop.

ToastContent

Root container passed as the children argument to renderToastRoot. Provides the rounded card layout and variant-matched background, border, and shadow.

ToastTitle

Headline text rendered as an <h6> with medium weight and variant-matched foreground color.

ToastDescription

Supporting body text rendered as a <p>. Accepts the same props as ToastTitle above.

ToastIcon

Styled icon container at the leading edge of the toast. Applies variant-matched foreground color so the icon contrasts correctly against the toast background.

ToastAction

Call-to-action button that auto-dismisses the toast after the action is triggered. Supports asChild for rendering a custom element such as a link.

ToastDismiss

Close button positioned at the top-left corner of the toast. Calls sonnerToast.dismiss(id) on click.

renderToastRoot

Imperative function that fires a toast via the Sonner API:

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

Accepts all additional Sonner ToastT options via props.

Accessibility

Toast is designed to meet WCAG 2.2 AA standards. Because toasts appear without a direct user action, choosing the correct live region semantics is critical for screen reader users.

Keyboard Interactions

ARIA

• Use role="status" with aria-live="polite" on ToastContent for non-critical, informational messages (confirmations, success feedback). This satisfies WCAG 4.1.3 Status Messages.
• Use role="alert" with aria-live="assertive" on ToastContent for urgent messages that require immediate attention (errors, session expiry warnings).
• Set aria-atomic={true} when the entire toast should be announced as a unit on each change.
• Always provide aria-label on ToastDismiss buttons (e.g. aria-label="Close"). Icon-only buttons have no visible text and require an explicit accessible name (WCAG 4.1.2 Name, Role, Value).
• Set aria-hidden={true} on ToastIcon when the icon is decorative and the adjacent text already conveys the meaning (WCAG 1.1.1 Non-text Content).
• ToastProvider sets containerAriaLabel="" and hotkey={['']} on the underlying Sonner Toaster to prevent duplicate announcements from the container element.
• All color variants meet the 4.5:1 text contrast ratio required by WCAG 1.4.3 Contrast Minimum in both light and dark mode.

Choosing the Right Component

Use Toast when you need a brief, auto-dismissing notification triggered by a user action. Reach for a different primitive when:

Related

• Alert
• Button
• Dialog