Toast

When to use one⁠link

Use a toast to confirm something the user just did, or to report work that finished in the background: "Draft saved", "Message sent", "The upload failed". A toast appears over the page without taking focus, and it leaves on its own, so the user carries on with what they were doing.

Use a dialog when the user must answer before going on, and a card for a message that has to stay on the page.

Try it⁠link

Each button shows a toast. Save sets an overline, a variant, and an icon, Send passes its text alone, and Upload keeps its toast on screen until you close it.

Options⁠link

showToast() takes a string, which becomes the toast's text, or an object with these options. Only content is required. An option you leave out takes its default from app configuration, where one exists.

overline, supportingText, and trailingSupportingText are always shown as text, never as HTML. How a toast appears and leaves comes from toastAnimation in app configuration, for every toast at once: Fade, Slide, or None.

Positions⁠link

A position names the block axis first, then the inline axis. In a left-to-right layout:

A right-to-left layout swaps left and right. App configuration's toastAnchor takes the four corners only, so a center is a choice you make for one toast, such as an error you show beside a dialog in the middle of the window.

Several at once⁠link

• Every call shows its toast at once. Chameleon doesn't hold toasts back in a queue, and it sets no limit on how many show together.
• Toasts at the same position stack, and the newest sits farthest from the window's edge. When one leaves, the others move along to close the gap.
• Toasts at different positions form separate stacks.
• When you change toastAnchor, toasts on screen that use it move to the new corner. A toast that set its own position stays where it is.
• When a modal dialog opens, toasts on screen move into it, so the user can still close them, and they move back when it closes.

How long it stays⁠link

• With Timer or CloseButtonAndTimer, a bar along the toast counts down its timeout, and the toast leaves when the time runs out.
• The countdown pauses while the mouse pointer is over the toast, while focus is inside it and while the page is hidden, then carries on with the time that was left. For a message the user needs time to read, use CloseButton or a longer timeout.
• A toast with an action, such as Undo, never leaves on its own and shows no bar. The Web components tab shows how to add one.
• With CloseButton, the toast shows no bar and stays until the user closes it.
• When the user's system asks for reduced motion, toasts appear and leave without animating, and the bar holds still. The toast still leaves when its time runs out.

How it closes⁠link

• Its close button closes it. Every toast shows one at its end.
• Escape closes it while focus is inside the toast. Inside a modal dialog, Escape closes the toast and leaves the dialog open.
• When a toast that has focus closes, focus moves to the next toast, or back to where the user was before reaching the toasts.
• Its timer closes it, with Timer or CloseButtonAndTimer, unless it has an action.

showToast() returns nothing, and Chameleon gives your code no way to close a toast once it's shown. Choose a timeout or a dismissMethod that fits the message instead. A toast with an action stays until the user closes it, whether or not they used the action.

Show a toast⁠link

Import showToast() from the package and call it wherever something happens that the user should know about.

import { showToast, ToastVariant } from "@materia-technologies-inc/chameleon-components-web";

showToast("Message sent");

showToast({
  overline: "Saved",
  content: "Your changes are safe",
  variant: ToastVariant.Success,
  leadingIconName: "check",
});

Text you didn't write⁠link

content is read as HTML. For text that comes from a user or a server, pass a DOM node whose text you set, or put the text in overline or supportingText, which are never read as HTML. A page that enforces Trusted Types refuses a string of markup, so pass a node or a TrustedHTML value from your own policy there.

import { showToast } from "@materia-technologies-inc/chameleon-components-web";

const content = document.createElement("span");
content.textContent = `${fileName} uploaded`;
showToast({ content });

Offer an action⁠link

To offer an action, such as Undo or Retry, pass a document fragment that holds the message and a button with slot="action". The button sits below the text, at the end of the toast. A toast with an action never closes by itself, so the user can always reach it, with F8 or Tab. It stays until the user closes it.

import { ButtonVariant, showToast } from "@materia-technologies-inc/chameleon-components-web";

const content = document.createDocumentFragment();
content.append("Message archived");

const undo = document.createElement("cw-button");
undo.slot = "action";
undo.setAttribute("variant", ButtonVariant.Text);
undo.textContent = "Undo";
undo.addEventListener("click", restoreMessage);
content.append(undo);

showToast({ content });

One toast in its own place⁠link

Give a toast its own position to show it somewhere other than the app's corner, such as beside a dialog in the middle of the window.

import { showToast, ToastDismissMethod, ToastPosition, ToastVariant } from "@materia-technologies-inc/chameleon-components-web";

showToast({
  content: "Those credentials weren't recognized",
  variant: ToastVariant.Error,
  position: ToastPosition.CenterCenter,
  dismissMethod: ToastDismissMethod.CloseButton,
});

Defaults for every toast⁠link

Set where toasts appear and how long they stay with setAppConfiguration(). App configuration lists every toast setting.

import { Corner, setAppConfiguration } from "@materia-technologies-inc/chameleon-components-web";

setAppConfiguration({ toastAnchor: Corner.EndEnd, toastTimeout: 8000 });

React apps call the same showToast(), imported from the React package. There's no toast component, provider, or hook to add.

Show a toast⁠link

Call showToast() from an event handler, an effect, or any code that runs after the work it reports.

import { CrButton, showToast, ToastVariant } from "@materia-technologies-inc/chameleon-components-react";

export function SaveButton({ onSave }: { onSave: () => Promise<void> }) {
  async function save() {
    await onSave();
    showToast({ overline: "Saved", content: "Your changes are safe", variant: ToastVariant.Success });
  }

  return <CrButton onClick={save}>Save</CrButton>;
}

showToast() takes every option on the Overview tab, with the same defaults. An action, such as Undo, is added the same way as on the Web components tab: a document fragment whose button has slot="action".

Text, not JSX⁠link

content takes a string of HTML, a DOM node, or a TrustedHTML value. It doesn't render a React element. For text that comes from a user or a server, put it in overline or supportingText, which are never read as HTML, or pass a DOM node whose text you set.

import { showToast } from "@materia-technologies-inc/chameleon-components-react";

const content = document.createElement("span");
content.textContent = `${fileName} uploaded`;
showToast({ content });

Defaults for every toast⁠link

Set where toasts appear and how long they stay with setAppConfiguration(), from the same package. App configuration lists every toast setting.

Blazor apps show a toast through IChameleonToastService, which AddChameleonServices() registers. Inject it into a component and call ShowToast().

Show a toast⁠link

ShowToast() comes in two forms. The first takes a severity, BlazorToastLevel.Info, Success, Warning, or Error, and picks the toast's variant, its icon, and an overline that names the level.

@inject IChameleonToastService ToastService

<CbButton OnClick="SaveAsync">Save</CbButton>

@code {
    private async Task SaveAsync()
    {
        await ToastService.ShowToast("Your changes are safe", BlazorToastLevel.Success);
    }
}

The overline it picks is the level's name in English, such as "Success". Pass heading to word it yourself, or to translate it. It also takes dismissMethod and timeout, which work as in the second form.

The second form takes the toast's parts one by one. Only content is required.

await ToastService.ShowToast(
    "Your changes are safe",
    overline: "Saved",
    leadingIconName: "check",
    variant: ToastVariant.Success,
    timeout: 8000);

The Blazor service has no per-toast position, supporting text, density, wave shape, icon flipping, or action. Set the position for every toast in the service's configuration, below, and density and wave shape in app configuration.

Configure the service⁠link

Assign a ChameleonToastServiceConfiguration in the options of AddChameleonServices().

using Chameleon.Blazor;

builder.Services.AddChameleonServices(options =>
{
    options.ChameleonToastServiceConfiguration = new ChameleonToastServiceConfiguration
    {
        Position = BlazorToastPosition.BottomCenter,
        Timeout = 8000,
        CloseMethod = ToastDismissMethod.CloseButtonAndTimer,
    };
});

The service always sends a timeout and a close method, so app configuration's ToastTimeout and DefaultToastDismissMethod don't reach the toasts it shows. Set Timeout and CloseMethod here instead.

Set the tokens⁠link

A toast takes its colors, type, and spacing from --ct-toast-* tokens. Chameleon adds toasts at the end of <body>, or inside an open modal dialog, so a token you set on your app's own container doesn't reach them. Set the tokens on :root, or on cw-toast to style every toast and nothing else.

cw-toast {
  --ct-toast-container-color: var(--ct-sys-color-inverse-surface);
  --ct-toast-label-text-color: var(--ct-sys-color-inverse-on-surface);
}

To style one kind of toast, pass a class in cssClass and set the tokens on that class. For a single toast, pass the declarations in cssStyle.

cw-toast.offline {
  --ct-toast-container-color: var(--ct-sys-color-surface-container-highest);
}

The tables below list every token. Each variant has its own tokens, and a variant's token falls back to the token of the same name without a variant, so --ct-toast-container-color changes every variant at once.

Each attribute value has its own tokens; a cell shows its token's value, and selecting the cell shows the token's fallback path, with each name and value ready to copy. For example, the primary-container column's action-hover-label-text-color row is --ct-toast-primary-container-action-hover-label-text-color, which defaults to same as --ct-toast-action-hover-label-text-color.

Variant⁠link

Other tokens⁠link

How it's announced⁠link

• Toasts sit in a region named "Notifications (F8)", so screen reader users can find them by landmark and learn the shortcut. The name is in the language the toast region inherits, usually the page's <html lang>.
• Each toast is read politely, once the screen reader finishes what it's saying, a moment after the toast appears.
• The overline, the message, the supporting text and the action's name are read. Keep them short, and put the outcome first.
• A toast with an action also says how to reach it: "Press F8 to reach the action".
• A toast never takes focus. The user's place on the page doesn't move when one appears.

Keyboard⁠link

• F8 moves focus to the newest toast, and again to the next older one. Tab also reaches the toasts, after the rest of the page. Inside an open modal dialog, they join the dialog's own tab order.
• A focused toast shows a focus ring, in a color that stands out on every toast color, and is read by its message.
• From the toast, Tab reaches the close button, then the action.
• Escape closes the toast while focus is inside it. Inside a dialog, it closes the toast and leaves the dialog open.
• When a focused toast closes, focus moves to the next toast. When none is left, it goes back to where the user was before reaching the toasts. If that place is gone, focus goes to the nearest control before the toast, then after it, then the page's main landmark. It falls to the top of the page only when nothing else can take focus.
• The close button's name is translated, such as Schließen in German.

Timing⁠link

• The countdown pauses while the mouse pointer is over the toast, while focus is inside it, and while the page is hidden, then carries on with the time that was left.
• Every toast that closes by itself has a close button.
• A toast with an action never closes by itself.

Your part⁠link

• Give the user time. Offer a setting that turns auto-dismiss off (CloseButton) or lengthens the timeout, and raise toasts with the user's choice.
• Never make a toast the only way to do something. A user may not reach it before it leaves.
• Keep toasts away from the controls people use most. A toast can cover the control that has focus.
• Say what the color says. An Error toast takes the theme's error color, and a user who can't see the color still needs to know. Name the outcome in the overline or the message, and add an icon.