Site color

Choose your site’s color palette.

Saved on this device.

ToastHost

ToastHostTransient feedback

Acknowledge the moment without interrupting the flow. Dismissible notifications with predictable lifetimes.

Actions & feedback

In context

Notification anatomyCOMPOSITION

AFTER AN ACTION

Local draft saved.5 seconds

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.

All notification tonesCOMPOSITION
neutral
neutral notificationUntil dismissed
accent
accent notificationUntil dismissed
feature
feature notificationUntil dismissed
secondary
secondary notificationUntil dismissed
custom
custom notificationUntil dismissed
ghost
ghost notificationUntil dismissed
info
info notification5 seconds
success
success notification5 seconds
warning
warning notification10 seconds
danger
danger notificationUntil dismissed

All 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.