Toast

Usage examples

import { Button, ToastProvider, getErrorMessage, useToast } from '@rookcom/monarch-react';

function ErrorButton() {
  const { toast } = useToast();
  return (
    <Button
      variant="danger-subtle"
      onClick={() =>
        toast.error(
          getErrorMessage(
            { response: { data: { message: 'That handle is already in use' } } },
            { fallback: 'Could not save the workspace' },
          ),
        )
      }
    >
      Save with a conflict
    </Button>
  );
}

<ToastProvider label="Error example notifications" position="bottom-center">
  <ErrorButton />
</ToastProvider>

import { Button, ToastProvider, useToast } from '@rookcom/monarch-react';

function ArchiveButton() {
  const { toast } = useToast();
  return (
    <Button
      onClick={() =>
        toast({
          title: 'Ticket archived',
          description: 'You can undo this.',
          tone: 'success',
          action: { label: 'Undo', onClick: () => {} },
        })
      }
    >
      Archive ticket
    </Button>
  );
}

<ToastProvider
  durationScale={2}
  label="Timing example notifications"
  position="top-right"
>
  <ArchiveButton />
</ToastProvider>

Purpose

Brief, transient feedback about an action that just happened, with one optional action such as Undo.

Design principles

• Mount ToastProvider once near the root; call toast() from useToast() anywhere below it.
• A toast never takes focus; it is announced through a live region and reachable with F8.
• Danger is announced assertively, everything else politely.
• Toasts with an action, and danger toasts, stay 10s by default; others 5s. Users can be given more time with durationScale.
• At most three are open (limit); older ones close first.
• Never put essential information only in a toast. Errors that block the user belong on the page as well.

API reference

import { ToastProvider, getErrorMessage, useToast } from '@rookcom/monarch-react';

toast(options) returns { id, dismiss }. toast.success, toast.error (danger), toast.warning and toast.info take (title, options?).

dismiss(id) closes one toast; dismiss() closes all.

useToast() throws outside ToastProvider.

getErrorMessage(error, { fallback, network }) turns any thrown value into one readable sentence: field errors, message, errors[], detail, from the response body first. Transport messages ("Request failed with status code 500", "Failed to fetch") and HTML error pages are replaced by the fallback.

Migrating from sonner: toast.success(msg, { action }) and toast.error(msg) have the same shape; action is { label, onClick }.

Generated from the TypeScript declarations of packages/react/src/components/feedback/toast.

Properties

ToastOptions: title, description, tone, action ({ label, onClick, altText }), duration, politeness, onDismiss.

Variants

States

Interaction behaviour

• Auto-dismisses after duration (5s; 10s for danger or with an action) times the provider’s durationScale. Infinity on either keeps it until dismissed.
• Pauses on hover and focus, and resumes when both leave.
• Activating the action runs onClick and dismisses the toast.
• The Dismiss button, Escape and a swipe close the toast.

Keyboard support

Focus is never moved to a toast automatically.

Accessibility

Role

region (named, with the hotkey) containing a list; each toast is a list item

Accessible name

The region is named by label plus the hotkey ("Notifications (F8)"); each toast by its title.

• Each toast is announced once through a separate live region: aria-live="assertive" for danger (or politeness="assertive"), polite otherwise. The list items carry no live role, so nothing is announced twice and the list stays valid.
• Toasts never steal focus (WCAG 2.4.3); F8 reaches them, so the action is keyboard accessible (2.1.1).
• Timing is adjustable (WCAG 2.2.1): hover or focus pauses, durationScale gives more time or turns auto-dismiss off.
• The close button is labelled dismissLabel (default "Dismiss") and described by the toast title, so several toasts stay distinguishable.
• The action announces altText (default its label) so screen-reader users know how else to do it after the toast is gone.
• Icons are aria-hidden. Reduced motion shortens the enter and exit animations to nothing.

Responsive behaviour

• The viewport is min(24rem, 100vw - 2rem) wide, so toasts fit narrow screens down to 320px.

Theme support

• Raised surface and tone accent tokens, so light, dark and high-contrast themes apply.
• Reduced motion shortens the enter and exit animations.

Do and don't

Related components

• Alert: Persistent message about a section.
• InlineNotice: Persistent one-line message next to a field, row or card.
• CalloutBanner: Persistent page-level banner.
• NotificationCenter: Planned persistent notification list.

Dependencies

Testing coverage

• Shows, runs the action (which dismisses) and dismisses with the close button.
• No axe violations with toasts of every tone open: list items carry no role (regression).
• Danger is announced assertively and other tones politely; politeness can be overridden.
• Never moves focus when a toast appears.
• F8 (or a custom hotkey) moves focus to the named region; Tab reaches the action; Escape dismisses.
• Each Dismiss button is labelled and described by its toast title.
• Keeps at most limit open; dismiss() closes all; onDismiss fires once each.
• Shorthands set the tone; a handle dismisses only its toast.
• Timing: 5s / 10s defaults, durationScale, Infinity, pause on focus and on hover.
• The action uses altText for screen readers.
• getErrorMessage: body before transport text, field errors, lists, fallbacks, network message.
• useToast throws outside a provider; renders on the server.

Tests: packages/react/src/components/feedback/toast