Toasts

A simple and unobtrusive mechanism to surface information.

Toasts provide the user with relevant information in the prominent yet unobtrusive bottom left position of the window (above the Homepage footer), keeping the UI free from clutter.

Toasts can be triggered by the Homepage as well as all Apps it embeds.

Use cases

How Toasts can add value to the user experience.

How Toasts can add value to the user experience.

Here are some common use cases for Toasts:

Table: Use casesUse caseTextActionExample

Guide the user to correct input	Enter a description.	–	Test
Confirm a completed action	Image created and saved.	–	Test
Make a change reversible	Removed from favorites.	Undo	Test
Ask the user to complete setup	Service credential needed.	Open	Test
Help recover from a temporary failure	Service is unavailable.	Retry	Test

See this Excel for all currently implemented Toasts.

Emitters

Which systems can trigger a Toast, and how they do it.

Which systems can trigger a Toast, and how they do it.

Toasts are emitted by the Homepage or by an embedded App. Apps decide which events produce a Toast and when to emit it; Homepage validates App requests and owns Toast presentation. App-specific interaction delays remain inside the App.

Homepage

Homepage can trigger a Toast via a function call.

Homepage can trigger a Toast via a function call.

Toasts inform the user of events within the Homepage system, for example if an API is unavailable.

Homepage triggers a Toast by calling its central function. Example:

Javascript: Request

showToast({
  source: "homepage:image-generator",
  severity: "success",
  title: "Image ready",
  message: "Your image was created and saved.",
  action: {
    id: "open-history",
    label: "Open",
    target: {
      type: "url",
      href: "#history"
    }
  },
  duration: 4_000,
  persistent: false,
  dedupeKey: "image-ready",
  contextKey: window.location.pathname
});

Detailed explanation of the request object:

Table: Request fieldsKeyValueMandatoryPurpose

	✗	Identifies the Homepage subsystem that triggered the Toast.
, , , or	✓	Sets the Toast's importance, appearance, and default duration.
	✗	Optional short headline.
	✓	Main text shown to the user.
An action object	✗	Adds one optional button.
	✓ when is used	Identifies the action.
	✓ when is used	Sets the button text.
A target object	✗	Defines what happens when the button is clicked.
or	✓ when is used	Selects who handles the action.
	✓ for a URL target	Gives Homepage the destination.
milliseconds	✗	Overrides the default duration.
or	✗	Stays until actively dismissed.
	✗	Groups repeated equivalent Toasts.
The current route	✗	Tells Homepage where the Toast originated.

Homepage represents an App-requested destination as ; the App Bridge request uses .

Apps

Apps can trigger a Toast via the Homepage bridge.

Apps can trigger a Toast via the Homepage bridge.

Toasts inform the user of events happening inside the App, for example if something was saved or not. The App owns event timing and sends a bridge request when its own state rules call for a Toast; Homepage does not infer App interaction state or add an activation delay.

Apps trigger a Toast via the Homepage bridge:

JSON: Request

{
  "type": "homepage/app/toast",
  "slug": "image-generator",
  "instanceId": "/app/image-generator#app:host",
  "severity": "warning",
  "title": "Almost there",
  "message": "Your service credential is missing.",
  "action": {
    "id": "open-settings",
    "label": "Open"
  },
  "dedupeKey": "credential-missing",
  "issueId": "credential-missing",
  "issueState": "active"
}

Detailed explanation of the request object:

Table: Request fieldsKeyValueMandatoryPurpose

	✓	Identifies this as an App Toast request.
App slug, such as	✓	Identifies the App sending the request.
The exact ID of the current App instance	✓	Ensures that the request and any later action belong to the correct App instance.
, , , or	✓	Sets the Toast's severity, appearance, and default duration.
Short text	✗	Adds an optional headline above the message.
Text for the user	✓ except resolve requests	Explains what happened or what the user should do.
An action object	✗	Adds one optional button to the Toast.
For example,	✓ when is used	Identifies the action sent back to the App.
For example,	✓ when is used	Sets the button text.
An approved URL or internal path	✗	Optional destination. If present, Homepage navigates to it. If absent, the App handles the action.
A duration in milliseconds	✗	Overrides the default duration, within Homepage's allowed limits.
or	✗	Keeps the Toast visible until the user dismisses it.
A stable identifier	✗	Groups repeated occurrences of the same event.
A stable issue identifier	✓ in Warning and Error	Identifies the active problem behind a Warning or Error Toast.
or	✓ in Warning and Error	Starts, updates, or resolves the associated issue.

Note: Apps often use a Homepage-provided API. If the API does not work, the App will see that and trigger a Toast that is sent to the Homepage bridge and displayed by the Homepage. The API itself does not trigger a Toast.

Elements

An overview and explanation of a Toast's UI elements.

An overview and explanation of a Toast's UI elements.

Toasts have a very simple UI. This section explains its elements.

Trigger this Toast to see all elements.

Title

Description and specification of the Toast title.

Description and specification of the Toast title.

Every Toast can display a Title, but it is optional. It is used to give the user context for the Toast's text.

List: Specifications

When present, the Title spans the upper line.
It is truncated with ellipsis if it exceeds the available width. The tone of the title is warm and slightly informal. It is used to add a human touch to info Toasts.

Add a title only if it adds to the user experience. Since it takes visual space, using a title must have a defensible reason.

Text

Description and specification of the Toast text.

Description and specification of the Toast text.

Every Toast must have a Text. It is used to give the user the information they need.

List: Specifications

The Text spans up to two lines.
It shares the available width with the optional Action.
The tone of the text is brief and informative.

Keep the text as short as possible. Try to start the sentence with a verb, use a direct, active, and supportive language.

Action

Description and specification of the Action button.

Description and specification of the Action button.

Toasts can have an optional Action button. It is used to allow users to react with just one click.

List: Specifications

The Action button sits on the right of the Text.
Its label can use up to half of the available width, with compact button padding accounted for separately so an otherwise-fitting label is not truncated.
The ideal length of its text is 1 word.

Use Actions when something can be repeated to solve or was destroyed permanently – or to navigate the user.

List: Click behavior

For an App-originated Toast, an Action without an href is handled by the App. An Action with an href is handled by Homepage as navigation.

Use Actions without an for App-specific operations. Use Actions with an to navigate the user.

Severity

Description and use cases of the severity indicator.

Description and use cases of the severity indicator.

Every Toast has a severity indicator, a colored circle at its right side:

Table: SpecificationsSeverityColorMeaningExampleReaction

Info	Gray	Neutral status or update	Test	Read and continue
Success	Green	An operation completed	Test	Continue
Warning	Yellow	Attention or recovery may be needed	Test	Review or act
Error	Red	An operation failed or cannot continue	Test	Correct, retry, or seek help

Toasts want to either inform the user about something that should interest them (Info, Success), make the user aware of an eventual issue (Warning), or guide them towards steps they have to take to resolve an issue (Error).

Behavior

How Toasts behave, and when and how to influence that.

How Toasts behave, and when and how to influence that.

The behavior of Toasts depends on several factors.

The common behavior is stacking to reduce clutter, automatic dismissal to reduce required reactions, and not interfering with the Homepage's navigation.

Duration

Details on how long a Toast is visible.

Details on how long a Toast is visible.

Most Toasts disappear by themselves. The duration depends on the Severity:

Table: Durations by SeveritySeverityDurationReasonExample

Info	4s	The user's awareness is not required	Test
Success	4s	The user's awareness is not required	Test
Warning	6s	The user should be aware of the issue	Test
Error	10s	The user must be aware of the issue	Test

While the user hovers a Toast, the dismissal countdown is paused. User can dismiss the Toast by clicking on it (except on the Action button). The dismissal of a Toast is not communicated to the source (only Action buttons can do that).

Toasts can opt out of auto-dismissal by setting the key to .

Javascript: Persistence

showToast({
  severity: "warning",
  message: "You really have to react.",
  persistent: true
});

A persistent Toast does not dismiss itself. The user must dismiss it manually, or trigger its Action if it has one.

Stacking

How Toasts are stacked and queued.

How Toasts are stacked and queued.

At most three Toasts are visible at once. Additional Toasts wait in a queue and appear when a slot becomes available.

They appear stacked in the UI. Repeated equivalent Toasts are grouped and show a count instead of appearing twice.

Navigating within Homepage does not dismiss or reset them.

Preferences

Errors and Warnings are deeply integrated.

Errors and Warnings are deeply integrated.

Warning and Error Toasts may have a corresponding issue in Preferences → Warnings. Both emitters can resolve an issue.

Homepage calls .
Apps send another request with the same , , , and , but with issueState: .

Resolving the issue removes it from the Warnings Box, does not create a new Toast, and may omit message.

Integration

Some details on the Homepage integration.

Some details on the Homepage integration.

The Toasts are tightly integrated with the Homepage.

The minimum width of a Toast is , their maximum width is . Action buttons use at most half of the available inside width.

Navigating away from an App does not clear related Toasts or unresolved issues. Reloading or replacing the App iframe does clear that App instance’s Toast state.

Toasts do not steal focus. In screen readers, they use polite status announcements by default. Reduced-motion preferences remove animation.

Appendix

Additional information.

Additional information.

Additional information for editors and admins.

Management

How to manage all these Toasts.

How to manage all these Toasts.

The Excel file Toast-Tracker_01.xlsx contains a living list of all currently available Toasts.

Testing

How to test the implementation.

How to test the implementation.

Links triggering Toasts can be triggered with this link format:

Markdown

[Test](toast://show?severity=warning&title=Title&text=Text.&button=Action)

Here is a Test. Toast links are unable to navigate the user.

Technology

Technological details.

Technological details.

The frontend library used to display toasts is Radix UI by WorkOS.