Toast UI

The toast system allows features to surface a message and an optional action for users to take. These are short notifications that serve as confirmation of a successful user action or provide contextual information about a Chrome initiated action. Each toast must have an icon and a body text; feature teams can optionally add an action or close button to toasts. Feature teams that want to introduce a toast will need to introduce a new value to the toast id enum and create a toast specification that will be registered with the toast registry.

Getting Started

1. Add a new entry to the ToastId enum

Each toast should have a unique ToastId which is used to identify the toast and retrieve its corresponding specification.

2. Register your ToastSpecification in ToastService::RegisterToasts()

The toast specification allows features to declare what components they want the toast to have. All toasts must have an icon and body text when shown, but have the option to add other components such as an action button, close button, three dot menu, or set the toast to be persistent.

Note: When registering your ToastSpecification, you can use strings with a placeholder. However, you must remember to pass in any values you want to use to replace the placeholders with in ToastParams when you trigger your toast.

Registering a Default Toast

void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .Build());
}

Registering a Toast with a Close Button

void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddCloseButton()
        .Build());
}

Registering a Toast with an Action Button

void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddActionButton(button_string_id, button_closure)
        .AddCloseButton()
        .Build());
}

Note: there are a couple restrictions when declaring a toast specification with an action button:

1. A toast with an action button must also have a "X" close button.
2. A toast with an action button cannot have a three dot menu.

Registering a Toast with a Menu

void ToastService::RegisterToast(BrowserWindowInterface* interface) {
  ...
  toast_registry_->RegisterToast(
    ToastId,
    ToastSpecification::Builder(vector_icon, string_id)
        .AddMenu()
        .Build());
}

Even though you have registered the toast with the ToastService, when you trigger the toast, you must remember to pass in a non-null menu model to populate the menu in ToastParams when you trigger your toast.

Also note that toasts with a menu cannot have a "X" close button. If this behavior is needed, please consult with UX on how to design this in a way that supports both.

3. Trigger your Toast

When you want to trigger your toast to show, you will need to retrieve the ToastController through BrowserWindowFeatures and call ToastController::MaybeShowToast(ToastParams params).

Note: the ToastController can be null for certain browser types so you must check if the controller exists before attempting to trigger the toast.

Triggering a Toast Without Needing to Replace Placeholder Strings

ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  toast_controller->MaybeShowToast(ToastParams(ToastId));
}

Triggering a Toast and Replacing Placeholder Strings

ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  ToastParams params = ToastParams(ToastId);
  params.body_string_replacement_params_ = {string_1, string_2};
  params.action_button_string_replacement_params_ = {string_3};
  toast_controller->MaybeShowToast(ToastParams(std::move(params)));
}

Triggering a Toast with a Menu

ToastController* const toast_controller = browser_window_features->toast_controller();
if (toast_controller) {
  std::unique_ptr<MyCustomMenuModel> menu_model = ...
  ToastParams params = ToastParams(ToastId);
  params.menu_model = std::move(menu_model);
  toast_controller->MaybeShowToast(ToastParams(std::move(params)));
}

Note: even though you have triggered your toast, there is a chance that users might not see the toast because another toast immediately triggered after your toast, thus preempting your toast from being seen by users.