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. Without closeLabel, the close button’s accessible label follows the page language. See Localization.

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>	✓	-