# Toast

Toasts are short, temporary messages used to inform users that a process was
performed. They provide visual feedback on the outcome of an action and require
minimal user interaction.

Toast, unlike common React components, is not a component that will be added to
your view. Instead, Toast is used by importing and calling the `showToast()`
function.

## Design & usage guidelines

Use `Toast` to present non-blocking feedback about the system to a user.

### Related components

For more persistent feedback (such as displaying errors), communicating a
background process that is ongoing, or for feedback that has a longer reading
length or CTA, use [Banner.](../Banner/Banner.md)

### Variation (Web only)

The primary use case for Toast is success messages.

In some cases, an informational Toast may be used to inform the user of some
background system activity. See
[Web/Info example](/storybook/web/?path=/story/components-status-and-feedback-toast--variation)

### Errors

> Do not use Toast for errors. This is currently an available variation, but
> should be considered deprecated and not propagated.

Use [Banner](../Banner/Banner.md) and, where necessary, targeted error messaging
(such as [InputValidation](../InputValidation/InputValidation.md)) so that the user can
appropriately assess and recover from the error.

## Content guidelines

The Toast label should be clear and concise, and should not take up more than
one line.

Use the pattern "action + subject" to maintain
[active voice](../voice-and-tone/voice-and-tone.md). The subject should be specific without
overloading too much detail for the user to parse at a quick glance.

| ✅ Do              | ❌ Don't                                            |
| ----------------- | -------------------------------------------------- |
| Saved job         | Saved job #216 - Weekly mowing for Nathaniel Lewis |
| Archived property | Archived 289 NW 198th St, Shoreline, WA 98177, USA |

* No need to use "Successfully", should be implicit in the Toast
* Don't use `Dismiss` or `Cancel` as an action label
  * Examples of action labels: `Undo`, `View`, `Refresh`
* Toast's label does not require a period
* Use sentence case, and only capitalize
  ["branded"](../product-vocabulary/product-vocabulary.md) Jobber features

| ✅ Do       | ❌ Don't                 |
| ---------- | ----------------------- |
| Saved job  | Saved Job Successfully. |
| Sent quote | Sent Quote              |


## Props

### Web

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `message` | `string` | Yes | — |  |
| `action` | `() => void` | No | — | **Deprecated**: action will be removed in the next major version @deprecated |
| `actionLabel` | `string` | No | — | **Deprecated**: actionLabel will be removed in the next major version @deprecated |
| `variation` | `"error" | "info" | "success"` | No | `success` |  |
