ToastHost
ToastHostTransient feedback Acknowledge the moment without interrupting the flow. Dismissible notifications with predictable lifetimes.
Actions & feedbackIn context
AFTER AN ACTION
Keep a toast brief. Put persistent instructions next to the task in an AlertBox.
An inline illustration of the host’s surface treatment. Use the live example below to trigger and dismiss actual viewport notifications.
<p class="text-eyebrow">AFTER AN ACTION</p>
<Panel tone="success" variant="surface">
<Flex align="center" justify="between" wrap="true">
<span>Local draft saved.</span>
<Badge tone="success">5 seconds</Badge>
</Flex>
</Panel>
<p>Keep a toast brief. Put persistent instructions next to the task in an AlertBox.</p> Timed and persistent feedback
Success disappears after five seconds; warning after ten. The error stays until dismissed. Notifications appear at the top of the viewport.
<RegorApp id="toast-host-demo" src="./playground.ts"/> import {
defineButtonComponents,
defineFlexComponents,
defineFormComponents,
defineIconComponents,
definePanelComponents,
defineToastComponents,
ToastStore,
} from '@purestack/ts-components'
import { SEMANTIC_TONES, type SemanticTone } from '@purestack/ts-style'
import { iconoir_xmark } from '@purestack/ts-svg-icons'
import { createApp, defineComponent, html } from 'regor'
export interface ToastHostExample {
notifications: ToastStore
save: () => void
warn: () => void
fail: () => void
clear: () => void
tones: SemanticTone[]
notifyTone: (tone: SemanticTone) => void
}
const toastHostExampleTemplate = html`<Flex direction="column">
<ToastHost :items="notifications.items" :dismiss="notifications.dismiss"/>
<Flex wrap="true">
<Btn tone="success" @click="save">Save local draft</Btn>
<Btn tone="warning" variant="outline" @click="warn"
>Show review reminder</Btn>
<Btn tone="danger" variant="outline" @click="fail"
>Show persistent error</Btn>
<Btn variant="link" @click="clear">Clear notifications</Btn>
</Flex>
<p>
Try every supported tone. Info and success last 5 seconds, warning lasts 10;
all others stay until dismissed.
</p>
<Flex wrap="true" aria-label="All notification tones">
<Btn
r-for="tone in tones"
:tone="tone"
variant="surface"
@click="notifyTone(tone)"
>{{ tone }}</Btn>
</Flex>
<FormStatus>{{ notifications.items.length }} active notifications</FormStatus>
</Flex>`
function createToastHostExample(): ToastHostExample {
const notifications = new ToastStore()
return {
notifications,
tones: SEMANTIC_TONES,
notifyTone: (tone) =>
notifications.notify(`${tone} example notification.`, tone),
save: () => notifications.notify('Local draft saved.', 'success'),
warn: () =>
notifications.notify('Review the content before publishing.', 'warning'),
fail: () =>
notifications.notify(
'Example build failed. Dismiss when acknowledged.',
'danger',
),
clear: notifications.clear,
}
}
const component = defineComponent<ToastHostExample>(toastHostExampleTemplate, {
context: createToastHostExample,
})
const icons: Record<string, string> = { 'iconoir:xmark': iconoir_xmark }
createApp(
{
components: {
ToastHostExample: component,
...defineToastComponents(),
...definePanelComponents(),
...defineFlexComponents(),
...defineButtonComponents(),
...defineFormComponents(),
...defineIconComponents((name) => icons[name] ?? ''),
},
},
{ selector: 'app#toast-host-demo', template: html`<ToastHostExample/>` },
) All notification tones
ToastHost always uses the surface variant and has no variant prop. All ten supported ToastStore tones appear below as inline illustrations.
neutralaccentfeaturesecondarycustomghostinfosuccesswarningdangerAll values are shown together. Switch the site theme to compare light and dark rendering.
Notification lifecycle
| Feature | What to try |
|---|---|
| Timed messages | Info and success disappear after 5 seconds; warning after 10. |
| Persistent messages | Every other tone remains until dismissed or cleared. |
| Individual dismissal | Use Dismiss on a live notification. |
| Stacking | Trigger several messages; they stack at the top of the viewport. |
| Clear the queue | Clear notifications removes all messages and timers. |
| Empty message | notify('') creates no notification. |
| Default tone | notify('Saved') uses info. |
Behavior and accessibility
Mount one host per store. ToastHost positions notices over the page and provides a labelled dismiss button. It does not create a live region itself; this example uses a FormStatus to announce the active count. Keep critical information in the page as well, so a disappearing toast is not the only record.
API reference
ToastHost contract
Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.
items
SRef<ToastItem[]> - Default
required
ToastStore.items: a shallow ref of ToastItem[] with id, message and SemanticTone.
dismiss
ToastStore['dismiss'] - Default
required
ToastStore.dismiss callback. Receives the ID of the notification to remove.
Composition
No slots. Register defineToastComponents with Flex, Panel, Btn and Icon dependencies. Include iconoir:xmark in the icon resolver.
ToastStore
| Method | Behavior |
|---|---|
notify(message, tone?) | Adds a toast. Default tone is info; empty messages are ignored. |
dismiss(id) | Removes one toast and clears its timer. |
clear() | Removes all toasts and clears all timers. |
Info and success expire after 5 seconds, warning after 10 seconds. Other tones persist. Call clear when a long-lived app removes the host.