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.
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.
Enumeration members
Name
Value
Animated
​
​
Success
​
​
Failure
​
​
Toast.ActionOptions
The options to create a Toast Action.
Properties
Property
Description
Type
title*
The title of the action.
string
onAction*
A callback called when the action is triggered.
(toast: Toast) => void
shortcut
The keyboard shortcut for the action.
​Keyboard.Shortcut​

Name	Description	Type
options*	The options to customize the Toast.	`Alert.Options`

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`

Name	Type	Description
hide	`() => Promise<void>`	Hides the Toast.
show	`() => Promise<void>`	Shows the Toast.

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`

Name	Value
Animated
Success
Failure

Property	Description	Type
title*	The title of the action.	`string`
onAction*	A callback called when the action is triggered.	`(toast:` `Toast) => void`
shortcut	The keyboard shortcut for the action.	`Keyboard.Shortcut`

Last modified 10mo ago