Toast is a temporary, self-dismissing notification triggered by user actions or system updates. It displays low-priority messages with minimal disruption. Toast can be used to communicate all Forge alert types except for Critical.

• A user action or system update triggers Toast to appear in the bottom left corner of the page, floating above page content.
• Screen readers announce Toast’s header and message.
• Toast is visible for 7 seconds, then fades over 3 seconds. If the user hovers over Toast or focuses on it via keyboard, it remains visible for as long as it’s in focus.
• Toast can include an optional action button to trigger an action when clicked (or activated via the custom keyboard shortcut Ctrl-Shift-1). This button often links to a page with more information.
• Once the user has read or interacted with the content in Toast, they can let it disappear or close it using the Dismiss button or the Close icon.

• To inform users of low-priority updates that don’t require an explicit acknowledgment, like a status change
• To confirm an event, like successfully submitting a form

• For an alert or information that needs to remain visible on the page, as Toast is temporary by design
• For information that requires immediate attention or action
• For critical alerts or warnings that users must acknowledge
• For an issue or status that affects an entire app, page, or section

Alert type

Toast is styled to reflect a Forge alert type (including indicator bar color, icon, and header text color). The Information alert type is the default. The Critical alert type isn’t available. This type is reserved for patient safety and other issues that are too important to convey using Toast, which is visible only temporarily.

Text

Toast allows for header text (1-3 words) and a message body. One or both of these fields should contain text when using Toast.

Action button

Toast includes an optional tertiary button for taking action based on Toast’s information. This is often used to open a page with more details, but you can customize the button for your use case. Clicking the button (or activating it with the custom keyboard shortcut Ctrl-Shift-1) closes Toast and triggers the action.

Toast automatically fades away after 7 seconds, so don’t use the optional action button for an important or mandatory action.

Make sure that Toast’s content displays the information that users need to decide whether to click the action button. Users taking action without sufficient information can cause errors and patient safety issues.

Options to close or dismiss

By default, Toast displays the Close icon in the upper right corner.

When Toast includes an action button, the Close icon is omitted, and the Dismiss button appears above the action button instead.

PHI, PII, and privacy

Don’t include protected health information (PHI) or personally identifiable information (PII) in Toast’s content if it might be seen by someone who shouldn’t have access to the information.

For example, in some clinical settings, providers and patients review the patient’s chart together on the provider’s screen during a visit. Patients shouldn’t see any PHI or PII (like another patient’s name, birthdate, or results, or other protected, identifying, or private information) in a Toast that appears during this time.

Multiple Toasts

Only one Toast appears at a time. If multiple Toasts are triggered at the same time or in quick succession, the most recent Toast is displayed.

Redundant information

Toast is temporary, so users might not read all the text, or they might miss the Toast altogether. Make sure that any important information displayed in Toast is also available in another location. For example, if Toast displays a notification of test results, these test results should also be accessible in the patient chart. There’s no way to reopen a Toast or its content after it disappears (unless your team builds this feature).

Toast includes a drop shadow and border to help separate it from the background.

Toast’s width is fixed at 375px, but its height depends on how long the content is; the max height is 105px.

If the optional action button is used, its width depends on its label text; the max width is 125px. This button is always located below the Dismiss button.

Animation

Toast appears instantly, remains visible for 7 seconds, and then fades over 3 seconds.

Toast appears in the bottom left corner of the page to minimize disruption and avoid blocking information and interactions on the page. This position is close to the browser’s status bar at the bottom of the viewport and can’t be changed.

The Forge team chose this position based on athenahealth research and best practices. However, we’re open to reconsidering these decisions, so please let us know about any use cases where you’d like Toast to behave differently.

Header

Toast’s header text should be 1-3 words long and use title case (“Lab Result”, not “Lab result”).

If header text exceeds 1 line, it’s truncated and ends in an ellipsis (“...”).

Message

Toast’s message body can be plain text or custom HTML, including formatted text and icons. Don’t use images, other non-text content, or interactive elements in Toast’s message. To add interactivity, use the optional action button.

Use sentence case for message text (“Your files have been added to this claim.”, not “Your Files Have Been Added To This Claim.”).

Toast has limited space and can display only a small amount of text. For help writing clearly and concisely, see Content.

Consider the purpose of your content, what it needs to communicate to users, and what you want them to do after reading it. Examples include:

• A very short, self-explanatory message that needs no action (“Your file uploaded successfully”)
• Brief information with just enough detail for users to decide whether to use the action button (like a patient’s name, date of birth, patient ID, and the words “Radiology report”)

Toast message text is truncated after the first 2 lines but does not end in an ellipsis (Toast doesn’t include an ellipsis for truncated message text, but your team can implement it). If your text is too long, consider:

• Revising your text to create a short, complete message
• Using the optional action button to give users a way to view the full message

Action button

Toast includes an optional action button. Use title case for button text (“View More”, not “View more”).

By default, screen readers announce the action button as “Press Crtl-Shift-1 to (action button label)”. Toast includes an alternative action button label for screen readers, in case your label doesn't work well in this format. For example, if the action button label is “Details”, then “Press Crtl-Shift-1 to Details” sounds strange. If the alternative action button label is set to “View Details”, screen readers would instead announce “Press Ctrl-Shift-1 to View Details”.

Timing and position

There are no props for setting Toast’s timing or position. These can’t be customized.

One Toast at a time

Toast appears very briefly, and only one Toast can appear at a time, regardless of how many Toast instances are in the React render tree and for how long. This leads to a few considerations when using Toast:

• The id prop is required and should be unique for every new Toast. If you use the same ID for different Toasts, you risk a new Toast not being displayed because it’s mistaken for a previously displayed Toast.
• Rendering a new Toast forces the currently displayed Toast to close immediately.
• If several Toasts are rendered in quick succession, some of them may not appear at all. This is acceptable because Toast shouldn’t be used for important information, and it’s OK if users don’t see it. You can use the onNeverShown callback to detect when this has happened.

Truncating message content

Whatever is passed in as children is rendered as the Toast message, below the header. This is only to allow text formatting (such as bold text or a break line) and icons. Don’t insert images, other non-text content, or interactive content in Toast.

To minimize workflow disruption, Toast’s space is limited on purpose. Toast’s message is truncated after the first 2 lines, but Toast doesn’t display an ellipsis to indicate this. You can add one using CSS (one of the uses of structured children). Here are 2 examples of how to do this: truncating single-line text and truncating multi-line text.

Implementation links

Toast directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Toast } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Toast from '@athena/forge/Toast';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Toast from '@athena/forge/dist/Toast';