Toast Message

Mount one ToastManager and ToastsRenderer for the application, then add messages through the manager.

Neutral toastPositive toastNegative toast

Show codeHide code

import { toast } from './ToastPageRoot';

export function BasicToast() {
  return (
    <div className="flex gap-8 flex-wrap">
      <button
        type="button"
        className="button-filled"
        onClick={() =>
          toast.neutral({ message: 'Item added to cart', timeout: 4000 })
        }
      >
        Neutral toast
      </button>
      <button
        type="button"
        className="button-filled"
        onClick={() =>
          toast.positive({ message: 'Payment successful', timeout: 4000 })
        }
      >
        Positive toast
      </button>
      <button
        type="button"
        className="button-filled"
        onClick={() =>
          toast.negative({ message: 'Connection lost', timeout: 4000 })
        }
      >
        Negative toast
      </button>
    </div>
  );
}

Setup

Create a single ToastManager instance for your app. Pass withViewTransitions for smooth animations.

import {
  ToastManager,
  ToastsRenderer,
  withViewTransitions,
  type BaseToastType,
} from '@volvo-cars/react-messages';

const toast = new ToastManager<BaseToastType>({
  onUpdate: withViewTransitions,
});

// In your app layout
<ToastsRenderer toastManager={toast} />;

Toast types

Three types indicate the nature of the message:

• toast.neutral() – General information
• toast.positive() – Success confirmations
• toast.negative() – Errors or warnings

Auto-dismiss

By default, toasts auto-dismiss after 4 seconds. Customize with the timeout prop (in milliseconds).

toast.positive({ message: 'Saved!', timeout: 2000 });

Set timeout: undefined or add an actionLabel to make the toast persist until dismissed.

With action

Add an action button with actionLabel and onAction. Toasts with actions don’t auto-dismiss and include a close button.

The toast.add() method returns the toast’s id, which you can use in callbacks to remove it.

Loading state

Show a spinner instead of the icon with loading: true. Useful for async operations.

Persistent toast

For important messages without actions, add closeLabel to show a close button and prevent auto-dismiss.

Behaviour

• Only one toast displays at a time. Additional toasts queue and appear when the current one dismisses.
• Hover or focus pauses the auto-dismiss timer.
• Press F6 to move keyboard focus to the toast region.
• Dismissing restores focus to the previously focused element.

Accessibility

Toasts use role="alert" for screen reader announcements. Key considerations:

• Don’t trigger toasts too frequently. Repeated interruptions can be disruptive
• For toasts with actions, disable auto-dismiss so users have time to interact
• Use toasts sparingly for users with cognitive or attention disorders
• Keep keyboard interaction and reading order intentional when a toast interrupts the current workflow
• When an action is present, write a clear, concise message and provide a manual dismiss control

See the accessibility guidelines for detailed information.

API

ToastManager

The manager controls the toast queue. Create one instance per app.

const toast = new ToastManager<BaseToastType>({
  onUpdate: withViewTransitions,
});

Methods:

Method	Description
neutral(options)	Show a neutral toast. Returns id.
positive(options)	Show a positive toast. Returns id.
negative(options)	Show a negative toast. Returns id.
remove(id)	Remove a specific toast by ID.
removeAll()	Clear all toasts.

Toast options

Option	Type	Default	Description
message	string	—	Required. The message text.
title	string	—	Optional title displayed above the message.
timeout	number	4000	Auto-dismiss delay in ms. Omit for persistent.
actionLabel	string	—	Label for action button. Disables auto-dismiss.
onAction	() => void	—	Callback when action button clicked.
closeLabel	string	—	Accessible label for the close button. Required to show the close button when there is no actionLabel.
onClose	() => void	—	Callback when close button clicked.
loading	boolean	false	Show spinner instead of icon.

ToastsRenderer

Prop	Type	Required	Default
toastManager	ToastManager<BaseToastType>	✓	-