kit-toast-region

<kit-toast-region></kit-toast-region>

<kit-toast-region> is a fixed-position container with aria-live="polite". The notificationModule() finds it and renders toasts on notification.show.

Place exactly one in your shell.

Package

@atheory-ai/kitsune-ui

import '@atheory-ai/kitsune-ui'
import { KitToastRegionElement, notificationModule } from '@atheory-ai/kitsune-ui'

shell.modules = [notificationModule(), /* others */]

Attributes

Attribute	Type	Default	Notes
`auto-dismiss-ms`	number	`4000`	Milliseconds before auto-dismissal. Set to `0` to disable.

Methods

Method	Notes
`show(message, tone)`	Append a toast. `tone` is `"info" \| "success" \| "error"`. Returns the new toast id.
`dismiss(id)`	Remove a specific toast.
`clear()`	Remove all toasts.

You’ll usually drive these via notificationModule() rather than calling them directly.

CSS custom properties

Property	Default
`--kit-space-4`	`1rem` (host inset)
`--kit-space-2`	`0.5rem` (gap between toasts)
`--kit-color-surface`	`Canvas` (toast background)
`--kit-color-border`	`CanvasText`
`--kit-radius-sm`	`0.375rem`
`--kit-color-success`	`oklch(60% 0.16 150)`
`--kit-color-error`	`oklch(58% 0.18 25)`

Positioning

By default, toasts appear in the bottom-right of the viewport. Override on the host:

kit-toast-region {
  /* top-center */
  inset-block-end: auto;
  inset-block-start: 1rem;
  inset-inline: 0;
  margin-inline: auto;
  align-items: center;
}

Triggering toasts

Via metadata (declarative):

<kit-button
  meta-command="notification.show"
  meta-prop-message="Saved"
  meta-prop-tone="success"
>
  Save
</kit-button>

Via runtime (programmatic):

runtime.command({
  type: 'notification.show',
  payload: { message: 'Saved', tone: 'success' },
})

From a module observing events:

runtime.on('note.saved', () => {
  runtime.command({ type: 'notification.show', payload: { message: 'Note saved', tone: 'success' } })
})

Accessibility

The container has role="region" aria-label="Notifications" aria-live="polite".
Each toast has role="status" (info/success) or role="alert" (error).
Polite regions wait for the user to finish their current activity; alerts interrupt.
For high-priority error messages, always use tone="error" so screen readers announce promptly.

Custom toasts

For toasts that need actions (e.g., “Undo”), the simplest path is to write your own region/module. The notificationModule is opinionated for the common case (text + tone + auto-dismiss).