# toast (https://docs.salla.dev/twilight/react/components/toast)



Use `toast` to tell the customer something happened, such as "Added to your cart", without interrupting them. For content that needs a decision, use [`Modal`](https://docs.salla.dev/twilight/react/components/modal).

## Example [#example]

```tsx title="app/components/cart/add-to-cart.ts"
import { toast } from '@salla.sa/twilight-theme-engine/toast';

export async function addToCart(productId: number) {
  return toast.promise(window.salla!.cart.addItem(productId), {
    loading: 'Adding...',
    success: 'Added to your cart',
    error: 'Could not add this product',
  });
}
```

`toast` is a plain function, not a React hook, so you can call it anywhere in the browser. The example reads the SDK from `window.salla`, which exists once the page runs in the browser, so call `addToCart` from an event handler. `useToast` is exported too and is the same function.

## API [#api]

```ts
toast(title: string, options?: ToastOptions): string | number;
toast.success | error | warning | info | loading(title, options?): string | number;
toast.dismiss(id?: string | number): void;
toast.update(id: string | number, options: { type?: ToastType; title?: string } & ToastOptions): void;
toast.promise<T>(promise: Promise<T>, options: ToastPromiseOptions<T>): Promise<T>;
```

Each call returns the toast's id, which you can pass to `toast.dismiss` or `toast.update`. `toast.update(id, { type, title })` replaces the toast in place, for example a `loading` toast that becomes a success. Leave out `title` to keep the current one. Passing `{ id }` to a variant does the same: `toast.success('Saved', { id })`.

| Prop               | Type                                 | Description                                                                                                   |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `description?`     | `string`                             | Second line under the title. The rest of `options` goes to the toast library (`duration`, `action` and more). |
| `promise: loading` | `string`                             | Message while pending. Required.                                                                              |
| `promise: success` | `string \| (data: T) => string`      | Message, or a function of the result. Required.                                                               |
| `promise: error`   | `string \| (error: Error) => string` | Message, or a function of the error. Required.                                                                |

## The Toaster [#the-toaster]

`Toaster` draws the toasts. The engine's `TwilightProvider` already mounts it, so a theme normally never renders one. Tune it through the provider instead:

| Prop                   | Type            | Description                                                                 |
| ---------------------- | --------------- | --------------------------------------------------------------------------- |
| `toast?`               | `boolean`       | On `TwilightProvider`: mount the `Toaster`. Default: `true`.                |
| `toastMobilePosition?` | `ToastPosition` | On `TwilightProvider`: position below 768px. Default: `"bottom-center"`.    |
| `addToCartToast?`      | `boolean`       | On `TwilightProvider`: show the default add-to-cart toast. Default: `true`. |

The same last two options are props of `Toaster` itself (`mobilePosition` and `addToCartToast`).

## Gotchas [#gotchas]

* Toasts show in the browser, and a `Toaster` must be mounted for anything to appear.
* `Toaster` also shows the messages the Salla SDK raises, for example after adding to cart. Inside the Salla mobile app it hands those to the native app instead. Your own `toast()` calls are always drawn by the `Toaster`.
* A page URL with `?success=message` or `?danger=message` shows that message once as a toast, then removes it from the address bar.
* On desktop toasts appear top-right, or top-left when the theme is RTL.
* If your theme shows its own add-to-cart feedback, set `addToCartToast={false}` to avoid two messages.

## Next [#next]

* [React to cart events](https://docs.salla.dev/twilight/react/recipes/react-to-cart-events) shows how to run code when the cart changes.
* [`Modal`](https://docs.salla.dev/twilight/react/components/modal) for dialogs.
* [Layout and components](https://docs.salla.dev/twilight/react/guide/layout-and-components)