# xpl-toast

Toasts are brief, non-disruptive messages that provide quick, at-a-glance feedback. They can have 3 sentiments; neutral, positive and negative and contain actions such as a button or link, or a close button. Messaging can include a title and caption limited to 85 characters. Keep your toast messaging short and to the point and tone in line with the sentiment of the Toast. 

The Toast component is configurable by Sentiment plus show/hide properties for Icon, Caption, Button and Dismissible. Use the nested component’s properties to customize further as needed. 

When possible, Toasts should auto-dismiss after 8 seconds. When an action is present, it may not be desirable to time out the Toast depending on your specific context.  

Match your messaging with the sentiment of the toast. Most messages will have a neutral sentiment. Reserve negative sentiments for when an explicit failure has occurred. Give users the information they need to correct the issue. 

Toasts only support a single action and up to 85 characters. If multiple actions can be taken, or the message is longer than a few words, use a [Modal component](https://apollo.xplordocs.com/?path=/story/components-modal--modal) instead.

## Positioning

The default position is arbitrarily set to `40px` from top and `40px` from right of the browser viewport on desktop and bottom-center on mobile. This position should be adjusted to ensure it's not covering your App's header. Apollo, by design, does not prescribe a position for toasts because this will be dependent on the app that it is being used in.

Positioning of toasts should be global to your app. For example, if it is decided that your app will always position the toast in the top right corner, then this convention should be followed throughout. It should not be positioned top-right on one screen and bottom-center on another.

*****Consult your designer for the best placement for your product.**

### Overriding the default position

The toast uses `position: fixed` and can be repositioned by overriding the `.xpl-toast` CSS class in your app's stylesheet. Set `top`, `right`, `bottom`, and `left` as needed and use `unset` or `initial` to clear any defaults you don't want.

**Top-left example:**
```css
.xpl-toast {
  top: 24px;
  right: unset;
  left: 24px;
}
```

**Bottom-right example:**
```css
.xpl-toast {
  top: unset;
  right: 24px;
  bottom: 24px;
}
```

**Centered at the top:**
```css
.xpl-toast {
  top: 24px;
  right: unset;
  left: 50%;
  transform: translateX(-50%);
}
```

The mobile breakpoint (≤ 768px) resets the toast to bottom-center. If your app needs a different mobile position, override the media query as well:

```css
@media screen and (max-width: 768px) {
  .xpl-toast {
    /* your mobile overrides */
    bottom: 16px;
    left: 50%;
    transform: translateX(-50%);
  }
}
```

> **Tip:** Place these overrides in a global stylesheet so every toast in your app appears in the same location.

<!-- Auto Generated Below -->


## Properties

| Property      | Attribute     | Description | Type                                  | Default     |
| ------------- | ------------- | ----------- | ------------------------------------- | ----------- |
| `caption`     | `caption`     |             | `string`                              | `undefined` |
| `dismissable` | `dismissable` |             | `boolean`                             | `true`      |
| `showIcon`    | `show-icon`   |             | `boolean`                             | `true`      |
| `timeout`     | `timeout`     |             | `number`                              | `8000`      |
| `variant`     | `variant`     |             | `"neutral" \| "success" \| "warning"` | `'neutral'` |


## Dependencies

### Depends on

- [xpl-icon](../xpl-icon)

### Graph
```mermaid
graph TD;
  xpl-toast --> xpl-icon
  style xpl-toast fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*