Toast

New

Alpine.js-powered toast notification stack. Toasts are queued, auto-dismissed, and dispatched from anywhere on the page via a global helper or custom DOM events.

API Reference

Place <c-toast /> once anywhere in your base template (typically at the end of <body>). It mounts an Alpine.js toastStack component that listens for kaiko:toast window events.

Call window.toast(message, type, duration) from any inline handler, Alpine expression, or plain JavaScript to push a notification onto the stack. Toasts auto-dismiss after duration ms (default: 4000). Pass persistent: true in the custom event detail to keep them until the user dismisses them manually.

c-toast

Attribute	Description	Type	Default
`position`	Corner / edge where the toast stack appears	string	`"bottom-right"`

window.toast() helper

Parameter	Description	Type	Default
`message`	Text content of the toast notification	string	`—`
`type`	Semantic style: controls colour and icon	string	`"info"`
`duration`	Auto-dismiss delay in milliseconds. Set to `0` to disable.	number	`4000`

kaiko:toast custom event detail

Field	Description	Type	Default
`message`	Notification text	string	`""`
`type`	Semantic type: `success` \| `error` \| `warning` \| `info`	string	`"info"`
`duration`	Auto-dismiss delay ms. `0` = no auto-dismiss.	number	`4000`
`persistent`	When `true`, never auto-dismisses regardless of `duration`	boolean	`false`

position values

top-left top-center top-right bottom-left bottom-center bottom-right

Base template integration


{% load static %}
<script src="{% static 'kaiko_ui/js/alpine-toast.js' %}" defer></script>

{# Place the toast container once, near the closing </body>: #}
<c-toast />

{# Or choose a different corner: #}
<c-toast position="top-right" />

Live region: the toast container uses role="status" and aria-live="polite" so screen readers announce new notifications without interrupting ongoing speech.

Dismiss: each toast has an accessible close button. Persistent toasts remain until the user explicitly dismisses them, making them suitable for critical or action-required messages.

Motion: toast entry/exit animations respect the user's prefers-reduced-motion preference.

Examples

Usage


<button onclick="window.toast('Saved successfully.', 'success')">
  Save
</button>

All Types

window.toast('This is an informational message.', 'info');
window.toast('Your changes have been saved.', 'success');
window.toast('Please review before continuing.', 'warning');
window.toast('An unexpected error occurred.', 'error');

Persistent Toast (No Auto-Dismiss)

window.dispatchEvent(new CustomEvent('kaiko:toast', {
  detail: {
    message: 'Action required: review the pending items.',
    type: 'warning',
    persistent: true
  }
}));

Custom Duration

<!-- 8-second duration -->
window.toast('This toast stays for 8 seconds.', 'info', 8000);

<!-- 1.5-second duration -->
window.toast('This toast disappears quickly.', 'success', 1500);

Alpine.js Integration

<div x-data="{
  saved: false,
  save() {
    this.saved = true;
    window.toast('Profile updated successfully.', 'success');
  }
}">
  <button class="btn btn-primary" @click="save()">
    Save profile
  </button>
</div>

<!-- Or dispatch the custom event from Alpine: -->
<button @click="$dispatch('kaiko:toast', { message: 'Saved!', type: 'success' })">
  Save
</button>