Choose a version:

Toast API

The Toast API lets you show brief, non-disruptive notification messages to customers. Use this API to confirm successful actions, surface errors, or provide lightweight feedback that appears temporarily and dismisses automatically.

Anchor to Use casesUse cases

Confirm a completed action: Show a success toast after the customer saves a preference, submits a form, or completes an operation.
Surface an error message: Display an error toast when a backend request fails or an action can't be completed, so the customer knows something went wrong.
Provide status updates: Notify the customer that a background process like data syncing or a submission has completed.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides toast notification functionality for customer account extensions. Access the following properties on shopify to show brief, non-blocking notification messages to the customer.

Anchor to toast toast required: Displays brief, non-blocking messages at the bottom of the page to confirm actions or report errors. Use noun + past tense verb format (for example, Changes saved). For persistent messages, use a Banner component instead.

ToastApi

Displays brief, non-blocking notification messages to the customer. Use the Toast API to confirm successful actions, report errors, or surface contextual feedback without interrupting the customer workflow.

show
Show a toast notification with the given message. Returns a handle with a `hide()` method to dismiss the toast programmatically.
```
(content: string) => Promise<ToastApiResult>
```

ToastApiResult

A handle returned by `ToastApi.show()`. Call `hide()` to dismiss the toast notification programmatically.

hide
Dismisses the toast notification.
```
() => void
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

async function handleSave() {

await shopify.storage.write(

'preferences_saved',

'true',

);

shopify.toast.show('Preferences saved');

}

return (

<s-button onClick={handleSave}>

Save preferences

</s-button>

);

}

Examples

Description

Display a toast notification after completing an action like saving preferences. This example calls `shopify.toast.show()` with a message string after a successful write to storage.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  async function handleSave() {
    await shopify.storage.write(
      'preferences_saved',
      'true',
    );
    shopify.toast.show('Preferences saved');
  }

  return (
    <s-button onClick={handleSave}>
      Save preferences
    </s-button>
  );
}

Description

Display an error toast when an operation fails so the customer knows to try again. This example wraps a fetch call in a try-catch block and passes `{isError: true}` to `shopify.toast.show()` on failure.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  async function handleSubmit() {
    try {
      const token =
        await shopify.sessionToken.get();
      const response = await fetch(
        'https://myapp.com/api/submit',
        {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${token}`,
          },
        },
      );

      if (!response.ok) {
        throw new Error('Request failed');
      }

      shopify.toast.show(
        'Submitted successfully',
      );
    } catch (error) {
      shopify.toast.show(
        'Something went wrong. Please try again.',
        {isError: true},
      );
    }
  }

  return (
    <s-button onClick={handleSubmit}>
      Submit
    </s-button>
  );
}

Anchor to Best practicesBest practices

Keep messages short: Toast messages should be a few words that confirm what happened, like "Preferences saved" or "Submitted successfully". Avoid long sentences.
Don't rely on toasts for critical information: Toasts disappear automatically. If the customer needs to take action, use a banner or inline message instead.

Anchor to LimitationsLimitations

Toast messages dismiss automatically after a short duration. You can't control how long they remain visible.
Only one toast can be displayed at a time. If you trigger multiple toasts in quick succession, earlier ones may be replaced.
Toast notifications don't support interactive elements like links or buttons. Use them for passive feedback only.

Was this page helpful?