# Toast
**Short messages at the edge of the screen that close on their own.**
**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/Toast) ยท [Zag.js Docs](https://zagjs.com/components/react/toast)
**ToastExamples.html**
```html
Send message
```
**Toaster.entry.ts**
```ts
import { mount } from 'fluid-primitives';
import { Toaster } from 'fluid-primitives/toaster';
// The page layout renders on every page.
export const toast = mount('ui:toaster', 'toaster', ({ props }) =>
new Toaster(props).init()
)!.store;
```
**Simple.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { toast } from '../Toaster/Toaster.entry';
mountAll('ui:toastExamples.simple', ({ createHydrator }) => {
createHydrator()
.query('actions')
?.addEventListener('click', () => {
toast.create({
type: 'success',
title: 'Message sent',
description: 'We usually reply within one business day.',
});
});
});
```
## Features
- Settings as Fluid props, toasts from any script through one `toast` export
- `success`, `info`, `warning`, `error` and `loading` toasts, styled through `data-type`
- Markup per type, such as an icon, and a template per type, which change in place with the type
- Closes after a duration per type and waits while you hover or focus it, or while the tab is in the background
- Lets the toasts overlap or lists them, and queues them beyond `max`
- Updates a toast in place instead of adding the same one twice
- Action trigger, close trigger and loading toasts that follow a promise
- `Alt+T` moves the focus to the toasts, `Escape` closes the focused one
- Screen readers announce new toasts through a live region
## Anatomy
```html
```
The toaster is the region the toasts appear in and holds their settings. Its `toastTemplate` is the template of one toast: the client clones it for every toast and fills in the title, the description and the label of the action trigger. A part keeps what the template puts into it while the toast has no text for it. An `indicator` shows markup for one type, and a `toastTemplate` with a `type` is the template of one type.
A toast template holds plain markup. A component that hydrates, such as `ui:button`, or a `ui:portal` inside it is cloned without its script, so it doesn't work in a toast.
## Installation
```bash
typo3 ui:add toaster toast
```
Or copy the files manually from GitHub into your project: https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/Toaster https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Registry/Toast
Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).
Render the toaster once in your page layout, with the `rootId` its entry file mounts:
```html
```
Without content, it renders the toast template you see in the demo above, with an icon for four types. Put a `ui:toaster.toastTemplate` inside to use one of your own. That replaces the default template, so one of yours has no `type`, for the toasts of every type without a template of its own. A toast template has exactly one root element, a `ui:toast.root`. The entry file exports the store of the toaster as `toast`. Import it wherever you create a toast:
```ts
import { toast } from '../Toaster/Toaster.entry';
toast.create({ type: 'success', title: 'Message sent' });
```
## Examples
### Create a toast
`toast.create()` returns the id of the toast, for `toast.update()` and `toast.dismiss()`. A toast takes a `title`, a `description`, a `type`, a `duration`, an `action`, `closable` and a `priority` from 1 (highest) to 8 for the queue. The store also has `remove()` (without the exit animation), `pause()` and `resume()`, `promise()`, and `success()`, `info()`, `warning()`, `error()` and `loading()` as shortcuts for the `type`.
### Pick a type
Each button below shows a toast of another `type`. The toast renders it as `data-type` and shows the `toast.indicator` of its type, the others are `hidden`. The toaster of the first demo has an indicator with an icon for four types, an `info` toast shows none. When the type changes, as in a promise, the indicators change with it. Only these five types can have an indicator and a template of their own. An icon in an indicator is decoration, so give it `aria-hidden="true"`. For screen readers, name the type in the title, or put visually hidden text such as "Error:" into the indicator. A `success` toast stays for 2 seconds, the others for 5 seconds. Set `duration` on the toast or on the toaster to change that.
**ToastExamples.html**
```html
SuccessInfoWarningError
```
**Types.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { toast } from '../Toaster/Toaster.entry';
const toasts = {
success: { title: 'Profile saved' },
info: { title: 'New opening hours', description: 'We open at 9:00 on Saturdays.' },
warning: {
title: 'Your session ends in 5 minutes',
description: 'Save your draft to keep it.',
},
error: { title: 'Payment failed', description: 'Your card was declined. Try another one.' },
};
mountAll('ui:toastExamples.types', ({ createHydrator }) => {
createHydrator()
.query('actions')
?.addEventListener('click', event => {
const type = (event.target as Element).closest('[data-type]')?.dataset
.type as keyof typeof toasts | undefined;
if (type) toast.create({ type, ...toasts[type] });
});
});
```
### Add an action
Pass an `action` with a `label` and an `onClick`. Click "Undo" in the toast: the action runs, and the toast closes.
**ToastExamples.html**
```html
Remove from cart
```
**Action.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { toast } from '../Toaster/Toaster.entry';
mountAll('ui:toastExamples.action', ({ createHydrator }) => {
createHydrator()
.query('actions')
?.addEventListener('click', () => {
toast.create({
title: 'Linen shirt removed from your cart',
action: {
label: 'Undo',
onClick: () => toast.create({ title: 'Linen shirt is back in your cart' }),
},
});
});
});
```
### Follow a promise
`toast.promise()` shows a `loading` toast until the promise settles, then turns it into the `success` or the `error` toast.
**ToastExamples.html**
```html
Send newsletter
```
**Promise.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { toast } from '../Toaster/Toaster.entry';
mountAll('ui:toastExamples.promise', ({ createHydrator }) => {
createHydrator()
.query('actions')
?.addEventListener('click', () => {
const sending = new Promise(resolve => setTimeout(resolve, 2000));
toast.promise(sending, {
loading: { title: 'Sending the newsletter' },
success: {
title: 'Newsletter sent',
description: 'It went out to 1,204 subscribers.',
},
error: { title: 'The newsletter could not be sent' },
});
});
});
```
### Update a toast instead of adding it twice
Give the toast an `id`, and update it while `toast.isVisible()` says it is still there. Click "Save draft" a few times: one toast counts the saves and shakes on every click. Screen readers announce the new description.
**ToastExamples.html**
```html
Save draft
```
**Deduplicate.entry.ts**
```ts
import { mountAll } from 'fluid-primitives';
import { toast } from '../Toaster/Toaster.entry';
const shake = [
{ transform: 'translateX(0)' },
{ transform: 'translateX(-4px)' },
{ transform: 'translateX(4px)' },
{ transform: 'translateX(-2px)' },
{ transform: 'translateX(0)' },
];
mountAll('ui:toastExamples.deduplicate', ({ createHydrator }) => {
let saves = 0;
createHydrator()
.query('actions')
?.addEventListener('click', () => {
if (!toast.isVisible('draft')) saves = 0;
saves++;
const draft = { title: 'Draft saved', description: `Saved ${saves} times.` };
if (saves === 1) {
toast.create({ id: 'draft', ...draft });
return;
}
// the new text is what screen readers announce, the shake is for everyone else
toast.update('draft', draft);
if (!matchMedia('(prefers-reduced-motion: reduce)').matches) {
document
.querySelector('[data-toast-root="draft"]')
?.animate(shake, { duration: 300 });
}
});
});
```
### List the toasts
The toasts overlap by default and spread out while you hover or focus them. Set `overlap` to `false` to list them one below the other. This demo has a toaster of its own, with another `placement` and its own `mount()`. Give every toaster of a page its own `placement`: two toasters with the same one share the id of their region, and `Alt+T` focuses only one of them.
**ToastExamples.html**
```html
Add to wishlist
```
**Stack.entry.ts**
```ts
import { mount, mountAll } from 'fluid-primitives';
import { Toaster } from 'fluid-primitives/toaster';
const wishlistToast = mount('ui:toaster', 'stack-toaster', ({ props }) =>
new Toaster(props).init()
)!.store;
const products = ['Linen shirt', 'Canvas tote', 'Wool scarf', 'Leather belt'];
mountAll('ui:toastExamples.stack', ({ createHydrator }) => {
let added = 0;
createHydrator()
.query('actions')
?.addEventListener('click', () => {
wishlistToast.create({
title: `${products[added++ % products.length]} added to your wishlist`,
});
});
});
```
### Give a type a template of its own
A `toastTemplate` with a `type` is the template of the toasts of that type, the one without a `type` the template of all others. When a toast changes to a type with another template, as when a promise fails, it stays in its place and takes the content of the new template:
```html
...
```
The title of this template says "Something went wrong" while the toast has no title of its own.
### Fill an element of your own
Pass the data of a toast as `meta`, and mark the element in the template with `ui:ref`. A subclass of `Toast` fills it, and a subclass of `Toaster` creates that toast. This demo has a toaster of its own for the cart, and each button passes the image of its product:
**ToastExamples.html**
```html
Add linen shirtAdd canvas toteAdd sunglasses
```
**Cart.entry.ts**
```ts
import type { Props } from '@zag-js/toast';
import { mount, mountAll } from 'fluid-primitives';
import { Toast } from 'fluid-primitives/toast';
import { Toaster } from 'fluid-primitives/toaster';
class CartToast extends Toast {
render() {
super.render();
const imageEl = this.hydrator.query('image');
const image = this.machine.service.prop('meta')?.image;
if (imageEl && image && imageEl.getAttribute('src') !== image) imageEl.src = image;
}
}
class CartToaster extends Toaster {
protected createToast(props: Props) {
return new CartToast(props).init();
}
}
const cartToast = mount('ui:toaster', 'cart-toaster', ({ props }) =>
new CartToaster(props).init()
)!.store;
mountAll('ui:toastExamples.cart', ({ createHydrator }) => {
createHydrator()
.query('actions')
?.addEventListener('click', event => {
const product = (event.target as Element).closest('[data-image]')?.dataset;
if (!product) return;
cartToast.create({
title: `${product.name} added to your cart`,
description: 'Ships in 1-2 business days.',
meta: { image: product.image },
});
});
});
```
Give such an element a fixed size, an image a `width` and a `height`: the toaster measures a toast when its content changes, not when an image loads.
A type change can swap every part of a toast except its root for the ones of another template. Query the parts in `render()`, as the cart toast does, and don't keep them or add listeners to them in `init()`. To animate the swap, override `replaceContent()` and call `super.replaceContent()` inside.
### Style the toasts with your own CSS
The client places every toast through CSS variables on its root, so your CSS has to use them: `--x` and `--y` for `translate`, `--scale` for `scale`, and `--z-index`, `--height` and `--opacity`. Transition them, and the toasts slide in, pile up and spread out. A closing toast has `data-state="closed"`, and a toast behind the front one has `data-sibling`:
```html
...
```
```css
.toast {
translate: var(--x) var(--y);
scale: var(--scale);
z-index: var(--z-index);
height: var(--height);
opacity: var(--opacity);
transition-property: translate, scale, opacity, height;
transition-duration: 400ms;
transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1);
}
.toast[data-state='closed'] {
transition-duration: 200ms;
}
/* a toast behind the front one takes the height of the front one, so hide what it holds */
.toast > * {
transition: opacity 400ms;
}
.toast[data-overlap][data-sibling] > * {
opacity: 0;
}
```
## Show TYPO3 flash messages
Write a component of your own that renders the flash messages as JSON and marks the `
```
Use it where your plugin template has `f:flashMessages`. It reads the same queue, the one of the plugin by default:
```html
```
`f:format.json` escapes `<` and `>`, so a message cannot end the `