ToastHost

Display dismissible notifications from a ToastStore, with semantic tones and predictable lifetimes.

ToastHost

View source ยท API reference

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 { 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
}

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>
  <FormStatus>{{ notifications.items.length }} active notifications</FormStatus>
</Flex>`

function createToastHostExample(): ToastHostExample {
  const notifications = new ToastStore()
  return {
    notifications,
    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 />` },
)

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.