Toast

When an asynchronous operation is happening or when an error is thrown, it's usually a good idea to keep the user informed about it. Toasts are made for that.

Additionally, Toasts can have some actions associated to the action they are about. For example, you could provide a way to cancel an asynchronous operation, undo an action, or copy the stack trace of an error.

The showToast() will fallback to showHUD() if the Raycast window is closed.

API Reference

showToast

Creates and shows a Toast with the given options.

Signature

async function showToast(options: Toast.Options): Promise<Toast>;

Example

import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const success = false;

  if (success) {
    await showToast({ title: "Dinner is ready", message: "Pizza margherita" });
  } else {
    await showToast({
      style: Toast.Style.Failure,
      title: "Dinner isn't ready",
      message: "Pizza dropped on the floor",
    });
  }
}

When showing an animated Toast, you can later on update it:

import { showToast, Toast } from "@raycast/api";
import { setTimeout } from "timers/promises";

export default async function Command() {
  const toast = await showToast({
    style: Toast.Style.Animated,
    title: "Uploading image",
  });

  try {
    // upload the image
    await setTimeout(1000);

    toast.style = Toast.Style.Success;
    toast.title = "Uploaded image";
  } catch (err) {
    toast.style = Toast.Style.Failure;
    toast.title = "Failed to upload image";
    if (err instanceof Error) {
      toast.message = err.message;
    }
  }
}

Parameters

Name

Description

Type

options*

The options to customize the Toast.

Alert.Options

Return

A Promise that resolves with the shown Toast. The Toast can be used to change or hide it.

Types

Toast

A Toast with a certain style, title, and message.

Use showToast to create and show a Toast.

Properties

Property

Description

Type

message*

An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset.

string

primaryAction*

The primary Action the user can take when hovering on the Toast.

Alert.ActionOptions

secondaryAction*

The secondary Action the user can take when hovering on the Toast.

Alert.ActionOptions

style*

The style of a Toast.

Action.Style

title*

The title of a Toast. Displayed on the top.

string

Methods

Name

Type

Description

hide

() => Promise<void>

Hides the Toast.

show

() => Promise<void>

Shows the Toast.

Toast.Options

The options to create a Toast.

Example

import { showToast, Toast } from "@raycast/api";

export default async function Command() {
  const options: Toast.Options = {
    style: Toast.Style.Success,
    title: "Finished cooking",
    message: "Delicious pasta for lunch",
    primaryAction: {
      title: "Do something",
      onAction: (toast) => {
        console.log("The toast action has been triggered");
        toast.hide();
      },
    },
  };
  await showToast(options);
}

Properties

Property

Description

Type

title*

The title of a Toast. Displayed on the top.

string

message

An additional message for the Toast. Useful to show more information, e.g. an identifier of a newly created asset.

string

primaryAction

The primary Action the user can take when hovering on the Toast.

Alert.ActionOptions

secondaryAction

The secondary Action the user can take when hovering on the Toast.

Alert.ActionOptions

style

The style of a Toast.

Action.Style

Toast.Style

Defines the visual style of the Toast.

Use Toast.Style.Success for confirmations and Toast.Style.Failure for displaying errors. Use Toast.Style.Animated when your Toast should be shown until a process is completed. You can hide it later by using Toast.hide or update the properties of an existing Toast.