Toast Message

Toast messages provide non-intrusive feedback about user actions. They appear briefly and auto-dismiss, or can persist when user interaction is required.

Neutral toastPositive toastNegative toast

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>
  );
}

Expand code Collapse code

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.

Remove item

import { toast } from './ToastPageRoot';

export function ToastWithAction() {
  return (
    <div>
      <button
        type="button"
        className="button-filled"
        onClick={() => {
          const id = toast.negative({
            message: 'Item removed from cart',
            actionLabel: 'Undo',
            onAction: () => {
              toast.remove(id);
              toast.positive({ message: 'Item restored', timeout: 2500 });
            },
          });
        }}
      >
        Remove item
      </button>
    </div>
  );
}

Expand code Collapse code

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.

Upload file

import { toast } from './ToastPageRoot';

export function ToastWithLoading() {
  return (
    <div>
      <button
        type="button"
        className="button-filled"
        onClick={() => {
          const id = toast.neutral({
            message: 'Uploading file...',
            loading: true,
            closeLabel: 'Cancel',
            onClose: () => toast.remove(id),
          });

          // Simulate upload completion
          setTimeout(() => {
            toast.remove(id);
            toast.positive({ message: 'Upload complete', timeout: 3000 });
          }, 3000);
        }}
      >
        Upload file
      </button>
    </div>
  );
}

Expand code Collapse code

Persistent toast

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

Show persistent toast

import { toast } from './ToastPageRoot';

export function PersistentToast() {
  return (
    <div>
      <button
        type="button"
        className="button-filled"
        onClick={() => {
          toast.negative({
            message: 'Connection lost. Check your network.',
            closeLabel: 'Dismiss',
          });
        }}
      >
        Show persistent toast
      </button>
    </div>
  );
}

Expand code Collapse code

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

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