Feedback

Stable - @kikita-labs/ui v1.6.1

Toast

Global notification service for non-blocking, auto-dismissing messages. Opened imperatively via kuiToast(), not rendered as a bound component instance.

Import

Import the inject-function and global options provider from the published package entrypoint.

toast.ts
import { kuiToast, provideKuiToastOptions } from '@kikita-labs/ui';

// Import runtime styles once, application-wide:
import '@kikita-labs/ui/styles';

Usage

Open in Playground

Inject kuiToast() once per component and call open() with a config object. The service lazily creates a single toast region on document.body the first time it is used, so there is nothing to render in your template.

<div class="basic-toast-example">
  @for (trigger of triggers; track trigger.appearance) {
    <button kuiButton type="button" shape="soft" (click)="show(trigger.appearance)">
      {{ trigger.label }}
    </button>
  }
</div>

With action button

Set actionLabel to render an inline action button. Clicking it emits once on the returned ref's action$ observable, which completes after emitting.

<button kuiButton type="button" shape="outline" appearance="danger" (click)="deleteMessage()">
  Delete message
</button>

Positions

The toast region renders at one of six positions. top-* stacks grow downward; bottom-* stacks grow upward, keeping the newest toast closest to the viewport edge. setPosition() changes the shared region at runtime and is intended for interactive demos like this one; prefer provideKuiToastOptions for real app configuration.

<div class="toast-position-example">
  @for (position of positions; track position) {
    <button kuiButton type="button" shape="soft" size="sm" (click)="show(position)">
      {{ position }}
    </button>
  }
</div>

Global defaults

provideKuiToastOptions configures app-wide defaults, including maxVisible, which has no runtime setter and can only be configured this way. Provide it once in app.config.ts or a route-level provider.

app.config.ts
export const appConfig: ApplicationConfig = {
  providers: [
    provideKuiToastOptions({
      position: 'top-end',
      duration: 4000,
      maxVisible: 5,
    }),
  ],
};

API

API verified against @kikita-labs/ui v1.6.1 public typings.

NameTypeDefaultDescription
titlestring-Required headline text passed to open().
messagestring | undefined-Optional supporting text below the title.
appearance'neutral' | 'success' | 'warning' | 'danger' | 'info''neutral'Visual intent. Controls the accent bar and icon color; neutral renders no icon.
actionLabelstring | undefined-Label for the inline action button. Clicking it emits once on KuiToastRef.action$.
durationnumber5000Auto-dismiss delay in ms. Ignored when persistent is true. App-wide default overridable via provideKuiToastOptions.
persistentbooleanfalseKeeps the toast open until the user closes it explicitly.
closablebooleantrueShows the close button. App-wide default overridable via provideKuiToastOptions.
showIconbooleantrueShows the appearance icon. App-wide default overridable via provideKuiToastOptions.
showProgressbooleanfalseShows a progress bar tracking time until auto-dismiss. App-wide default overridable via provideKuiToastOptions.
kuiToast()() => KuiToastService-Inject-function returning a reusable opener bound to the current injector scope. Call once per component; prefer over injecting KuiToastService directly.
KuiToastService.open(config)(config: KuiToastConfig) => KuiToastRef-Shows a toast notification and returns a ref for programmatic control.
KuiToastService.setPosition(position)(position: KuiToastPosition) => void-Changes the shared toast region position at runtime. Intended for interactive demos; prefer provideKuiToastOptions for app-level configuration.
KuiToastRef.close()() => void-Closes this toast programmatically and plays the exit animation.
KuiToastRef.closed$Observable<void>-Emits once after the close animation finishes, then completes.
KuiToastRef.action$Observable<void>-Emits once when the action button is clicked, then completes.
provideKuiToastOptions(options)(options: KuiToastOptions) => Provider-App or route-level provider for global toast defaults: position, duration, maxVisible, showProgress, closable, showIcon.
position'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end''bottom-center'Global region position. Set app-wide via provideKuiToastOptions, or at runtime via KuiToastService.setPosition for demos.
maxVisiblenumber3Max simultaneous toasts, set via provideKuiToastOptions. The oldest visible toast is evicted when exceeded. Not changeable at runtime.

Accessibility

Toast uses a polite live region instead of stealing focus, matching how assistive technology expects transient status messages to behave.

  • The toast region has aria-live="polite", so new toasts are announced without interrupting current speech.
  • Toasts do not capture keyboard focus on appear, unlike Dialog. Keep critical, blocking confirmations in a Dialog instead of a toast.
  • Hovering a toast pauses its auto-dismiss timer; leaving resumes it with the remaining time. This gives pointer users time to read before it disappears, but there is no keyboard-equivalent pause gesture documented yet — treat persistent as the safer choice for messages a keyboard-only user must be able to act on.
  • Set persistent for errors or messages requiring a response instead of relying on the default 5 second auto-dismiss.
  • prefers-reduced-motion replaces slide animations with an opacity-only fade.
  • On the server, KuiToastService.open() returns a no-op ref and performs no DOM access, so calling it during SSR is safe.