# Toast component for Stripe Apps

Inform users of temporary status.

# v8

> This is a v8 for when app-sdk-version is 8. View the full page at https://docs.stripe.com/stripe-apps/components/toast?app-sdk-version=8.

To add the Toast component to your app:

```js
import { showToast } from "@stripe/ui-extension-sdk/utils";
```

Render a toast at the bottom of your view to inform the user about the status of an action. For example, a toast can show a user whether an API call succeeded or failed.

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = () => {
    fetch(...)
      .then((response) => {
        showToast("Invoice updated", {type: "success"})
        return response.json()
      })
      .catch(() => {
        showToast("Invoice could not be updated", {type: "caution"})
      })
  }

  // Use the `handleClick`...
}
```

The `showToast()` function takes two arguments, a `message` and `options`. The function is defined as follows:

```ts
type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
const showToast: (message: string, options?: ToastOptions) => Promise<{
    update: (updateMessage: string, updateOptions?: ToastOptions) => void;
    dismiss: () => void;
}>;
```

Toast messages can’t exceed 30 characters in length or be empty. If a message is too long or empty, the console logs an error.

Unless they’re of type `pending`, toasts dismiss automatically.

| Is Pending | Has Action | Timeout |
| ---------- | ---------- | ------- |
| `false`    | `false`    | 4s      |
| `false`    | `true`     | 6s      |
| `true`     | `false`    | None    |
| `true`     | `true`     | None    |

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    const { dismiss, update } = await showToast("Refreshing data", {
      type: "pending",
    });
    try {
      await refreshData();
      dismiss();
    } catch (error) {
      update("Data could not be refreshed", { type: "caution" });
    }
  }

  // Use the `handleClick`...
}
```

Toasts can also prompt the user to take an action. Clicking the action button automatically dismisses the toast.

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    let timeout;
    const { dismiss } = await showToast('Message "sent"', {
      action: "Undo",
      onAction: () => {
        clearTimeout(timeout);
        showToast('Message "unsent"');
      },
    });
    timeout = setTimeout(() => {
      sendMessage();
      dismiss();
    }, 3000);
  }

  // Use the `handleClick`...
}
```


# v9

> This is a v9 for when app-sdk-version is 9. View the full page at https://docs.stripe.com/stripe-apps/components/toast?app-sdk-version=9.

To add the Toast component to your app:

```js
import { showToast } from "@stripe/ui-extension-sdk/utils";
```

Render a toast at the bottom of your view to inform the user about the status of an action. For example, a toast can show a user whether an API call succeeded or failed.

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = () => {
    fetch(...)
      .then((response) => {
        showToast("Invoice updated", {type: "success"})
        return response.json()
      })
      .catch(() => {
        showToast("Invoice could not be updated", {type: "caution"})
      })
  }

  // Use the `handleClick`...
}
```

The `showToast()` function takes two arguments, a `message` and `options`. The function is defined as follows:

```ts
type ToastType = "success" | "caution" | "pending" | undefined;
type ToastOptions = { type?: ToastType; action?: string; onAction: () => void; }
const showToast: (message: string, options?: ToastOptions) => Promise<{
    update: (updateMessage: string, updateOptions?: ToastOptions) => void;
    dismiss: () => void;
}>;
```

Toast messages can’t exceed 30 characters in length or be empty. If a message is too long or empty, the console logs an error.

Unless they’re of type `pending`, toasts dismiss automatically.

| Is Pending | Has Action | Timeout |
| ---------- | ---------- | ------- |
| `false`    | `false`    | 4s      |
| `false`    | `true`     | 6s      |
| `true`     | `false`    | None    |
| `true`     | `true`     | None    |

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    const { dismiss, update } = await showToast("Refreshing data", {
      type: "pending",
    });
    try {
      await refreshData();
      dismiss();
    } catch (error) {
      update("Data could not be refreshed", { type: "caution" });
    }
  }

  // Use the `handleClick`...
}
```

Toasts can also prompt the user to take an action. Clicking the action button automatically dismisses the toast.

```ts
import {showToast} from '@stripe/ui-extension-sdk/utils';

const App = () => {
  const handleClick = async () => {
    let timeout;
    const { dismiss } = await showToast('Message "sent"', {
      action: "Undo",
      onAction: () => {
        clearTimeout(timeout);
        showToast('Message "unsent"');
      },
    });
    timeout = setTimeout(() => {
      sendMessage();
      dismiss();
    }, 3000);
  }

  // Use the `handleClick`...
}
```


## See also

- [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md)
- [Style your app](https://docs.stripe.com/stripe-apps/style.md)
- [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)