# Toast

## Description

Toasts are brief user feedback messages that overlay content.

## Usage

You should not use the toast components directly. Instead use the JavaScript API exported from Warp Elements to create, update and remove toasts

<style-isolate id="toast-usage">
    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show toast</w-button>
</style-isolate>


```js
import { toast } from '@warp-ds/elements/toast';

const showBtn = document.getElementById("toast-btn");
showBtn.onclick = () => {
    toast("Toasts are somewhat of an anti-pattern");
};
```

### Dismissable toast

The toast automatically closes by default, so you don't need to have a close button.

From an accessibility perspective, toasts should never contain interactive elements such as close buttons, as interactive elements should always appear in the same location as the action that triggered them.

It might be tempting to use this option and a high duration if you have a warning or error toast to "solve" the WCAG 2 success criteria 2.2.1, but please consider showing warnings and errors as a persistent [Alert](/docs/components/alert/overview) instead.

If the toast absolutely must be dismissible by the user, set the `canclose` property to `true`.

```js
toast('message goes here', { type: 'success', canclose: true });
```

## Accessibility

From an accessibility perspective, toasts should never contain interactive elements, as these should always appear in the same location as the action that triggered them.

Auto-clearing toasts based on a timeout violate WCAG 2 success criteria 2.2.1, unless the information they contain is either redundant (i.e. also available elsewhere in a persistent manner) or insignificant to all people.

You are also advised to avoid putting information in a toast that cannot be re-accessed in any other way due to the impermanent nature of the current toast implementation.

Because of these points we consider the use of toasts to be somewhat of an anti-pattern, and recommend exploring alternative approaches wherever possible. That said, you may still use toasts, as long as you avoid interactive elements like links or close buttons.

## Examples

### Success / positive

This is the default.

<style-isolate id="toast-usage">
    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern')">Show a success toast</w-button>
</style-isolate>

### Warning

If the user should be warned about something, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.

A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for warnings).

<style-isolate id="toast-usage">
    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'warning' })">Show a warning toast</w-button>
</style-isolate>

### Error / negative

If the user should be told about an error, a toast is probably not the right way to do so. Consider an [Alert](/docs/components/alert/overview) instead.

A toast is easy to miss, especially on larger screens. Toasts that automatically close are also an accessibility problem if the information is not available elsewhere, or is insignificant (which shouldn't be the case for errors).

<style-isolate id="toast-usage">
    <w-button id="toast-btn" onclick="toast('Toasts are somewhat of an anti-pattern', { type: 'error' })">Show an error toast</w-button>
</style-isolate>

## API Documentation

### toast

```js
import { toast } from '@warp-ds/elements/toast';

const theToast = toast('Toasts are somewhat of an anti-pattern');
```

Returns [ToastOptions](#toastoptions), which includes the ID you need for [updateToast](#updatetoast) and [removeToast](#removetoast).

If you can't pass the result from `toast` to where you call `updateToast` or `removeToast` you can set a known ID manually.

```js
toast('Toasts are somewhat of an anti-pattern', {
    id: 'something-unique-but-stable',
});
```

| Parameter | Type |  Summary |
| --- | --- | --- |
| message | `string` | The text content |
| options | [ToastOptions](#toastoptions) (optional) | |


### updateToast

```js
import { toast, updateToast } from '@warp-ds/elements/toast';

const theToast = toast('The toast function returns an ID');

updateToast(theToast.id, 'Use it to update the text');
```

Returns [ToastOptions](#toastoptions).

| Parameter | Type |  Summary |
| --- | --- | --- |
| id |  `string` | The ID of the toast you want to update |
| message | `string` | The new text content |
| options | [ToastOptions](#toastoptions) (optional) | |

### removeToast

Toasts disappear after a set time, but if you need to remove one before that happens you can do so.

```js
import { toast, removeToast } from '@warp-ds/elements/toast';

const theToast = toast('The toast function returns an ID');

removeToast(theToast.id);
```

### Types

#### ToastOptions

| Name | Type | Default | Summary |
| --- | --- | --- | --- |
| id | `string` | Random | Random generated unique ID for the toast element |
| type | [`ToastVariants`](#toastvariants) | `'success'` | Visual style of the toast |
| text | `string` | `-` | The given toast message |
| duration | `number` | `5000` | Duration of toast in milliseconds |
| canclose | `boolean` | `false` | See [Dismissable toast](#dismissable-toast) |

#### ToastVariants

`'success' | 'warning' | 'error'`