Toast

Toast renders an accessible notification viewport for messages created through useToast(). Visual type and announcement urgency are independent, duplicate messages are allowed, stable ids update in place, and timers pause while users inspect the queue.

Anatomy

• #toast: Replaces all content inside the library-owned accessible toast root.
• #title: Replaces title content.
• #description: Replaces description content.
• #close: Replaces close-button content.

The viewport and each toast root remain library-owned so live-region, queue, swipe, limit, and lifecycle behavior cannot be removed accidentally.

Usage

<script setup lang="ts">
import { Toast, useToast } from "akaza-ui";

const toast = useToast();
</script>

<template>
  <button @click="toast.add({ title: 'Saved', description: 'Settings updated.' })">
    Show toast
  </button>
  <Toast />
</template>

Examples

Visual type and urgency

Use type for styling and priority for announcement urgency. error and alert default to high priority; all other types default to low priority.

toast.add({
  title: "Storage nearly full",
  description: "Less than 10% remains.",
  type: "warning",
  priority: "high",
});

Duplicates and stable updates

Calls without id create independent notifications, even when content is identical. Reusing an id updates that toast, increments updateKey, and restarts its timer.

toast.add({ title: "Comment received" });
toast.add({ title: "Comment received" }); // Separate toast

toast.add({ id: "sync", title: "Syncing", duration: 0 });
toast.update({ id: "sync", title: "Synced", type: "success", duration: 5000 });

Action button

Actions close after successful completion by default. Set closeOnSelect: false to keep the toast open. Rejected actions emit action-error and remain visible.

toast.add({
  title: "Connection lost",
  duration: 0,
  action: {
    label: "Retry",
    altText: "Retry connection",
    onSelect: reconnect,
  },
});

Promise updates

toast.promise() preserves one id while the source promise moves from loading to success or error.

await toast.promise(api.publish(), {
  loading: { title: "Publishing", duration: 0 },
  success: { title: "Published", type: "success" },
  error: { title: "Failed", type: "error" },
});

Custom content

#toast owns all inner markup. Root role, live-region attrs, swipe handlers, type/state attrs, and queue metadata remain intact. Notification metadata and the guarded default action lifecycle are exposed directly to custom content.

<Toast>
  <template #toast="{ toast, type, priority, action, performAction, close }">
    <article :data-type="type" :data-priority="priority">
      <strong>{{ toast.title }}</strong>
      <p>{{ toast.description }}</p>
      <button v-if="action" @click="performAction($event)">{{ action.label }}</button>
      <button @click="close()">Dismiss</button>
    </article>
  </template>
</Toast>

Scoped manager for SSR

Default manager is a convenient client-side singleton. Create and provide a scoped manager for SSR or independent notification regions.

<script setup lang="ts">
import { createToastManager, provideToastManager, Toast } from "akaza-ui";

const manager = provideToastManager(createToastManager({ duration: 6000 }));
</script>

<template>
  <RouterView />
  <Toast :manager="manager" />
</template>

API Reference

Toast Props

Emits

useToast

ToastAddOptions

Slots

UI Options

Styling Hooks

Toast geometry follows its viewport edge. Bottom positions enter from below and expand upward; top positions enter from above and expand downward. A new toast slides in while existing toasts move and scale behind it in the same transition. Collapsed toasts expose only a scaled edge while content behind the frontmost toast fades out. The stack uses a 500ms eased transform, with separate 150ms height and 250ms content transitions. Override the duration variables as needed. Active swipe tracking remains immediate, and reduced-motion preference shortens all transitions automatically.

Keyboard