Toast usage guidelines

Caution

This component is currently in an unstable state and may undergo significant changes in future releases.

A toast is a short, non-intrusive message that appears briefly at the top of the page, overlaying content, to provide feedback in response to user actions or server updates.

When to use

• To provide brief, non-intrusive feedback on successful user actions (e.g., “Form successfully submitted”).
• To confirm a server update or background process completion.
• To communicate minor, non-critical errors that don’t block user progress or require user action.

When not to use

• Use alert for persistent messages that need to remain visible until addressed.
• Use callout for proactive, general announcements or updates that are not triggered by a specific user action.

Properties

Tone

Preview

InfoSuccessWarningCritical

Code

import { Button, Stack, UNSTABLE_toastQueue, UNSTABLE_ToastRegion } from '@cimpress-ui/react';

const TONES = ['info', 'success', 'warning', 'critical'] as const;
const MESSAGES = {
  info: 'Auto-save is enabled',
  success: 'Your changes have been saved',
  warning: 'Your session is about to expire',
  critical: 'Error saving changes, please try again or contact support',
} as const;

export default function Demo() {
  return (
    <>
      <UNSTABLE_ToastRegion />
      <Stack direction="horizontal" gap={16}>
        {TONES.map((tone) => (
          <Button
            key={tone}
            onPress={() => {
              UNSTABLE_toastQueue[tone](MESSAGES[tone]);
            }}
          >
            {tone.charAt(0).toUpperCase() + tone.slice(1)}
          </Button>
        ))}
      </Stack>
    </>
  );
}

Copy code Open in playground

Tone	Use cases
Success	Used for confirmation of successful actions, processes, and positive outcomes.
Info	Used for important details without implying positivity or negativity.
Warning	Used for non-critical issues, potential problems that won’t block user progress, and recommendations for attention.
Critical	Used for critical issues that will block user progress or otherwise need to be addressed.

Formatting and layout

Placement

Toasts appear at the top-center of the screen, overlaying content. Toasts should not be overused in a single page, but if a user receives multiple toast messages at the same time they stack vertically with the most recent message being at the top of the screen.

Content writing

• Do keep messages short and to the point. Because toasts dismiss on a timer, it is important any written content is short enough users can read it before the toast disappears.
• Do focus on the immediate outcome of the action or update that triggered the toast.
• Do not include any actions or links in toasts.

Behaviors

Dismissing toasts

Toasts automatically dismiss after 5 seconds by default. Users can manually dismiss a toast earlier by clicking the close icon (X). For important messages that should remain visible until explicitly acknowledged, toasts can be configured to be persistent and will only dismiss when the user clicks the close icon.