Toast - Web

For development, import toast from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The Toast consists of four primary elements that work together to create temporary alerts that appear as a direct result of a user action.

Title
Body content
Actions
Close button

Options

The Toast supports the following configurations to accommodate various notification scenarios.

Status

Type	Description
Informational	Non-essential information as the result of a user action.
Success	Confirmation that a task was successfully completed.
Warning	Information to warn users of a potential issue as the result of an action. Often paired with an action to help users recover.
Critical/Error	Used to communicate an error or other failure. Often paired with an action to help users recover.

Content Area

At minimum, a Toast consists of a title. Toasts also support body content, including a body message, actions, or progress bar.

AI Mark

Include an AI Mark in a Toast when the title should indicate AI-generated content.

Usage Guidelines

Standard	Requirement
DoNo interruption needed	The user does not need to be interrupted.
DoInforming with optional action	The user is being informed of an event, with the option to take action.
DoDelayed action results	The results of an action are delayed.
DoAppear anywhere in the application	The notification could appear anywhere in the application.

See the notification pattern for additional guidance.

Status Variations

Informational

Communicates operational information to the user. These are commonly used to denote the start of an operation, and usually includes follow-up notifications.

Success

Communicates the success of an operation, e.g., user preferences were updated. Avoid including the term “successfully” in success Toasts as it duplicates information.

Critical/Error

Critical Toasts are used when an operation was unable to be performed or has failed. Page-specific and form errors should utilize the Alert notification. When applicable, users should be able to take action on an operation.

Warning

Warnings are distinct from errors and represent issues that do not need an immediate resolution, but still need to be addressed. Unintended consequences in an operation and fallback choices are common examples. In general, users should be able to take action on a warning.

Alternatives

Toast vs Alert

Alerts are used to communicate information about either part of a page or a whole page. Alerts can be used to summarize information, such as a summary of errors. Toasts are brief pieces of information and usually appear as the result of user action.

Toast vs Announcement

Announcements are used to convey app-wide messages, such as a new release being available, application maintenance, or sandbox information. Toasts are short pieces of information usually prompted by user action.

Behavior

The Toast responds to timing requirements and positioning constraints while maintaining consistent notification appearance.

How to Use

Positioning

Toasts are positioned in the top-right of the screen on top of application UI. Toasts do not cover any part of the global navigation.

Timing

By default, Toasts are persistent until dismissed by a user. An optional timeout is available. The recommended duration is 8 seconds, but this can be customized. Toasts are always persistent in the following cases:

When there are any actions within the Toast.
When a Toast contains a Progress Bar.
When a Toast is in an error state.

Avoid adding a timeout when a Toast contains information that users may need to copy or remember.

Progress Bar

When the time to complete a task can be calculated, pair a Toast with a Progress Bar.

Content

Content within the Toast should be brief, scannable, and actionable.

Titles should be brief and scannable and as specific as possible.

Use sentence case. Don’t use periods and exclamation points, and avoid articles: a, an, the.

Write titles as verbs

Titles should have a clear verb + noun question or statement.

Toast "Do" example that has title that says "Unable to create geofence"
and body text that says "We weren't able to create the geofence. Please try
again."

Don’t

Messages that can be communicated in a single header don’t require body text.

Body text should only provide information that is not included in the header. Do not repeat information that’s already in the header.

Toast "Do" example with only a title that says "Geofence created
successfully"

Don’t

Make body content concise, informative, and actionable

Use imperative verbs when telling users what they need to know or do. Avoid permissive language like “you can”. Whenever possible, include an in-line action for a user to take so that they can readily address the issue explained in the message.

Toast "Do" example with title that says "Some drivers haven't been mapped"
and body text that says "All drivers must be mapped to a technician before
you can move to the next
step."

Don’t

Buttons should be clear, predictable, and action-oriented

Users should be able to predict what will happen when they click a button. Lead with a strong verb that encourages action. Use a verb/noun pair on actions in most cases. Common actions like Save, Close, or Cancel do not require an accompanying noun.

Toast "Do" example that has title that says "Submission error" and body
text that says "An issue was encountered process the request. Please try
again or view the results for more details." and two buttons. The first
button says "Try Again" and the second button says "View
Results"

Don’t

Code

Implementation
Toaster Props
Toast Methods

Common Examples

Toast methods

There are seven toast methods available in Anvil2. Four of them are used to create standard toasts with varying styles:

toast.info()
toast.success()
toast.warning()
toast.danger()

The fifth, toast.promise(), generates a pending toast, and uses a completed promise to update the toast based on a response.The other two are used to manage existing toast messages:

toast.update()
toast.dismiss()

import { Button, toast } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <Button
      onClick={() =>
        toast.info({
          title: "Toast title",
          message: "Lorem ipsum dolor sit amet",
        })
      }
    >
      Click me!
    </Button>
  );
}

Toasters

To use the toast methods, there must be a Toaster component rendered somewhere up the tree, usually at the root of the application. The toaster is the container that toast messages appear in, and manages positioning, stacking, and dismiss timing updates.

import { AnvilProvider, Toaster } from "@servicetitan/anvil2";

function App({ children }) {
  return (
    <>
      <Toaster id="app-toaster" />
      <AnvilProvider>
        {children}
      </AnvilProvider>
    </>
  )
}

Multiple toasters

In order to avoid double-rendering toast messages, the Toaster component will only render toast messages if it doesn’t detect another Toaster. This means if you are using a Toaster in a standalone MFE, it will display toasts, but will defer to the host’s Toaster when it is loaded in the host application.Note: A limitation exists where the Toaster cannot detect a Toaster in a sibling MFE. For this reason, there must be a Toaster in the host app to which MFEs will defer.

Toaster config

To ensure consistency, the Toaster component should handle most of the config options for toast messages within an app. The following props can be added:

type ToasterProps = {
  // defaults
  id: string;
  focusKey?: string; // "t"
  toastsBeforeStack?: number; // 3
};

Showing basic toasts

Basic toast method examples

Toast method config object

All of the basic toast methods accept a config object with the following shape:

type toastProps = {
  title: string;
  actions?: { primary: ToastAction; secondary?: ToastAction };
  aiMark?: boolean | AiMarkWithTooltipOrPopoverConfig;
  containerClassName?: string;
  duration?: number | false;
  message?: string;
  onClose?: MouseEventHandler<HTMLButtonElement>;
  onDismiss?: () => void;
  progress?: number | "indeterminate";
  toastClassName?: string;
}

Notes for basic toast methods

Toasts with actions will ignore the duration setting to allow users a chance to perform an action.
The toast config passed to a toast method will override some of the defaults set on the Toaster component.

Using promise toasts

Promise toast example

Promise toast method config object

The config object passed to toast.promise() should have three properties – loading, success, and error.

type PromiseToastMethodConfig = {
  loading: toastProps; // same as basic config object
  success: (message: string) => toastProps;
  error: (message: string) => toastProps;
};

Notes for promise toasts

The first parameter of the toast.promise() method should be a Promise that either resolves or rejects. Otherwise, the loading state will render indefinitely.

Using progress toasts

The progress property can be passed to any toast creation method or toast.update() to display a Progress Bar inside the toast.

Notes for progress toasts

Set progress to a number from 0–100 for a determinate progress bar, or "indeterminate" for an indeterminate one.
Use toast.update() to advance the progress value as work completes.
Set duration: false to prevent the toast from auto-dismissing before the operation finishes.
When the operation completes, use toast.update() with a new status to change the toast’s visual style.

Updating toasts

Notes for updating toasts

An id for the toast message to be updated is required as the first parameter of the toast.update() method. This id is provided as the return value of any of the toast creation methods.
Any of the toastProps can be updated using this method, including progress.
status can also be set in toast.update() to change the toast’s visual style (e.g. changing from "info" to "success" when an operation completes).

Dismissing toasts

When toasts are dismissed

Toasts without actions auto-dismiss after the duration expires.Toasts with actions ignore the duration setting and are only dismissed when the user takes direct action: pressing the “x” button, clicking a toast action button, or calling toast.dismiss() programmatically.

Toasts can be dismissed in four ways:

By pressing the “x” button on the toast message.
By swiping the toast message off the screen on touch screens.
Automatically after the duration expires, if supplied on the Toaster or in the toast method.
Programmatically using the toast.dismiss() method.

Notes for dismissing toasts

The toast.dismiss() method accepts an optional id parameter to dismiss a specific toast message. This id is given as the return value of any of the toast creation methods.
If no id is provided, all visible toast messages will be dismissed.
If a duration is provided, and the toast becomes stacked (hidden), the timeout is paused and restarted once the toast becomes visible again.

Callbacks for toast dismissal

There are two callback parameters available on the toast methods:

onClose is passed to the “x” button’s onClick, so it is only run when the user activates the button
onDismiss is run anytime the toast is removed, including on “x” button click, when toast.dismiss() is run, or when the duration expires on the toast

Using toast actions

The actions property of the toastConfig that is passed to toast creation methods can be used to add one or two Button components to the toast message. The actions property accepts an object with two properties:

type ActionsParameter = { primary: ToastAction; secondary?: ToastAction };

The ToastAction type is used to update some Button props of the action button.

type ToastAction = Pick<ButtonProps, "appearance" | "onClick"> & {
  label: string;
};

AI Mark

Add an AI Mark inline after the toast title by including aiMark in the toast config. Use true for the sparkle only, or pass tooltip or popover configuration.

Toast event handling

Whenever a toast is added, updated, or dismissed, the Toaster component runs the onToastEvent callback with the following object passed in the event:

type ToastEventType = {
  eventType: "add" | "update" | "dismiss" | "dismiss-all";
  toastCount: number;
  id?: string;
  toasterId?: string;
  toastProps?: ToastProps | ToastUpdateProps;
};

Some of the parameters will only show when certain toast methods are called. For example, toast.dismiss() will not include toastProps, since it affects all of the existing toasts.

MFE Toaster note for toast event handling

The Toaster used in the monolith/host app will take precedence over any loaded by an MFE, so the onToastEvent will generally not work for MFEs that are run in a host app that includes its own Toaster, such as monolith.

React Accessibility

When actions are used, do not add a duration so that users have time to decide if they would like to take action.
By default, pressing the “t” key on the keyboard while a toast message is visible will shift focus to the toast. This is announced by screen readers to make the messages easily accessible for some users. If the “t” key is used for another hot key, this can be overridden using the focusKey prop of the Toaster.

For further guidance on creating accessible status updates, see accessible status messages and notifications best practices.

<Toaster
  id="app-toaster"
  focusKey="t"
  toastsBeforeStack={3}
  onToastEvent={(event) => console.log(event)}
/>

`Toaster` Props

MFE Warning: When a Toaster is used in an MFE that is loaded into monolith, or any other host app that includes its own Toaster, the host app Toaster will take precedence. Any props used on an MFE Toaster will only work when it is used outside of the host app. This allows for a centralized config and rendering in the host application.

string

required

string

default:"t"

Hot key for focusing on first toast message.

(toastEvent: ToastEventType) => void

See Toast event handling

number

default:"3"

Determines how many toasts to show before they stack in the UI.

// Basic toast methods
toast.info({ title: "Info", message: "Message" });
toast.success({ title: "Success", message: "Message" });
toast.warning({ title: "Warning", message: "Message" });
toast.danger({ title: "Danger", message: "Message" });

// Promise toast
toast.promise(promise, {
  loading: { title: "Loading..." },
  success: (message) => ({ title: "Success", message }),
  error: (message) => ({ title: "Error", message }),
});

// Update toast
toast.update(id, { title: "Updated", message: "New message" });

// Dismiss toast
toast.dismiss(id);

Toast Methods

Basic toast creation methods API

This API applies to the following methods:

toast.info()
toast.success()
toast.warning()
toast.danger()

toastProps

See Toast method config object.

This API applies to the toast.promise() method:

Promise

See Notes for promise toasts.

{ loading: toastProps, success: (message: string) => toastProps, error: (message: string) => toastProps}

See Promise toast method config object.

Updating toasts API

This API applies to the toast.update() method:

string

See Updating toasts.

Partial<toastProps> & { status?: "info" | "success" | "warning" | "danger" }

Only add properties that should change. Use status to change the toast’s visual style on update.

Dismissing toasts API

This API applies to the toast.dismiss() method:

string

If omitted, all toasts are dismissed. See Updating toasts.

​Anatomy

​Options

​Status

​Content Area

​AI Mark

​Usage Guidelines

​Status Variations

Informational

Success

Critical/Error

Warning

​Alternatives

​Toast vs Alert

​Toast vs Announcement

​Behavior

​How to Use

​Positioning

​Timing

​Progress Bar

​Content

​Titles should be brief and scannable and as specific as possible.

​Write titles as verbs

​Messages that can be communicated in a single header don’t require body text.

​Make body content concise, informative, and actionable

​Buttons should be clear, predictable, and action-oriented

​Code

​Common Examples

​Toast methods

​Toasters

​Multiple toasters

​Toaster config

​Showing basic toasts

​Basic toast method examples

​Toast method config object

​Notes for basic toast methods

​Using promise toasts

​Promise toast example

​Promise toast method config object

​Notes for promise toasts

​Using progress toasts

​Notes for progress toasts

​Updating toasts

​Notes for updating toasts

​Dismissing toasts

​When toasts are dismissed

​Notes for dismissing toasts

​Callbacks for toast dismissal

​Using toast actions

​AI Mark

​Toast event handling

​MFE Toaster note for toast event handling

​React Accessibility

​Toaster Props

​Toast Methods

​Basic toast creation methods API

​Updating toasts API

​Dismissing toasts API

Anatomy

Options

Status

Content Area

AI Mark

Usage Guidelines

Status Variations

Alternatives

Toast vs Alert

Toast vs Announcement

Behavior

How to Use

Positioning

Timing

Progress Bar

Content

Titles should be brief and scannable and as specific as possible.

Write titles as verbs

Messages that can be communicated in a single header don’t require body text.

Make body content concise, informative, and actionable

Buttons should be clear, predictable, and action-oriented

Code

Common Examples

Toast methods

Toasters

Multiple toasters

Toaster config

Showing basic toasts

Basic toast method examples

Toast method config object

Notes for basic toast methods

Using promise toasts

Promise toast example

Promise toast method config object

Notes for promise toasts

Using progress toasts

Notes for progress toasts

Updating toasts

Notes for updating toasts

Dismissing toasts

When toasts are dismissed

Notes for dismissing toasts

Callbacks for toast dismissal

Using toast actions

AI Mark

Toast event handling

MFE Toaster note for toast event handling

React Accessibility

`Toaster` Props

Toast Methods

Basic toast creation methods API

Updating toasts API

Dismissing toasts API