useToast

useToast() returns a notification manager. Toast renders its queue and handles announcements, focus, swipe dismissal, and transitions. Mount a viewport for each manager you want to display.

Usage

Capture the manager in setup. Add notifications from handlers, not while rendering the template.

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

const toast = useToast();

function notify() {
  toast.add({ title: "Changes saved", type: "success" });
}
</script>

<template>
  <button type="button" @click="notify">Save</button>
  <Toast />
</template>

The example omits visual styles. Use the Toast component's ui prop and slots to style the viewport and notifications.

Examples

Update instead of duplicating

Reuse an ID for one notification that changes over time. Calls without an ID create separate messages, even when their text is identical.

toast.add({ id: "upload", title: "Uploading", duration: 0 });
toast.update({ id: "upload", title: "Upload complete", type: "success", duration: 5000 });

Updating restarts the timer and reopens a closing item. Updating an unknown or removed ID does nothing. Use add if the item might not exist.

Type and announcement priority

Visual type does not dictate a color or icon. It is metadata exposed by Toast for your classes and slots. Priority determines screen-reader urgency.

toast.add({ title: "Connection lost", type: "error" });
toast.add({ title: "Review your settings", type: "warning", priority: "low" });

alert and error default to high priority. Other types default to low. Override priority when a message's urgency differs from its visual type.

Persistent message with an action

Use duration: 0 when automatic dismissal would be inappropriate. Toast executes the action; the manager stores its metadata.

toast.add({
  title: "Project archived",
  duration: 0,
  action: {
    label: "Undo",
    altText: "Restore the archived project",
    closeOnSelect: true,
    onSelect: () => restoreProject(),
  },
});

restoreProject is application code. The Toast action lifecycle covers async actions and custom slots.

Promise results

promise updates one notification when an existing promise settles. It returns the resolved value and rethrows a rejection, so handle failures in the calling workflow.

try {
  const project = await toast.promise(saveProject(), {
    loading: { title: "Saving", duration: 0 },
    success: value => ({ title: `Saved ${value.name}`, duration: 5000 }),
    error: { title: "Could not save", duration: 0 },
  });
  openProject(project);
} catch {
  // Keep the editor open so the user can retry.
}

saveProject and openProject belong to your application. The helper accepts a promise, not a request factory, and defaults settled notifications to success or error unless their options override the type.

Scoped managers

The following helpers are also public exports. Create a manager in setup to keep queues separate or establish an explicit SSR boundary.

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

const manager = provideToastManager(createToastManager({ duration: 6000 }));

function notify() {
  manager.add({ title: "Workspace saved", type: "success" });
}
</script>

<template>
  <button type="button" @click="notify">Save workspace</button>
  <Toast :manager="manager" />
</template>

Descendant setup calls to useToast() receive the provided manager. In the providing component itself, use the returned manager or useToast(manager). To bypass injection and choose a specific queue, pass its manager explicitly to both useToast(manager) and <Toast :manager="manager" />.

createToastManager

createToastManager(options?: ToastManagerOptions): ToastManager;

An independently created manager does not automatically become the default. Connect it through a provider or explicit manager prop.

provideToastManager

provideToastManager(manager?: ToastManager): ToastManager;

Call it in ancestor component setup. Omitting the argument creates a manager with defaults. It returns the manager it provides. Providers belong to a subtree; they are not a process-wide notification store.

API Reference

Signature

useToast(manager?: ToastManager): ToastManager;

Resolution order is explicit manager, injected manager, then the default app manager during SSR or shared default in the browser.

Manager

Toast's hover and focus behavior already pauses its manager. Use pause and resume only when an application-owned interaction needs the same behavior.

ToastAddOptions

Action, updates, and lifecycle

ToastAction requires label and onSelect(event?). Optional altText explains the action to assistive technology. closeOnSelect defaults to closing after a successful action; set it to false to leave the notification open.

ToastUpdateOptions<T> requires id and accepts partial item fields except state and updateKey, which the manager owns. ToastPromiseOptions<T> requires loading, success, and error; success and error can be option objects or callbacks.

ToastItem<T> contains the add fields plus required id, type, priority, duration, state, and updateKey. State is open or closing. Close reasons are action, close-button, escape, swipe, timeout, and programmatic.

SSR and ownership

Call the default useToast() in setup and capture it for later handlers. A server call outside setup needs an explicit manager. Create that manager per request or component, never as a module-level SSR singleton. Manager timers run only in the browser.

The composable supplies state, not accessible DOM. Use Toast for announcements and dismissal. A custom renderer must implement those behaviors itself.

Related

• Toast component, slots, and styling
• useOverlay