Configuration
Toastflow resolves config in three layers:
Internal defaults
Shipped by toastflow-core.
Global config
Passed to createToastflow(...) (Vue) or createToastStore(...) (headless).
Per-toast overrides
Passed to show, typed helpers, loading, or update.
packages/core/src/types.ts. The table below covers the most common options.Common Options
| Option | Default | What it controls |
|---|---|---|
position | "top-right" | Viewport anchor for the stack |
duration | 5000 | Auto-dismiss delay in ms. Infinity / 0 = no auto-dismiss |
maxVisible | 5 | Max visible toasts per position. <= 0 = no cap |
queue | false | Queue overflowed toasts instead of evicting |
order | "newest" | Insert order and eviction target |
progressBar | true | Show progress bar for finite durations |
pauseOnHover | true | Pause timer on hover or touch |
pauseStrategy | "resume" | "resume" continues remaining time, "reset" restarts full duration |
closeButton | true | Show floating close button |
closeOnClick | false | Dismiss on body click |
showIcon | true | Show the type icon |
preventDuplicates | false | De-duplicate by position + type + title + description |
supportHtml | false | Allow HTML in title and description (use trusted content only) |
sanitizer | — | Hook sanitizing HTML before render, e.g. DOMPurify (details) |
swipeToDismiss | false | Dismiss with a right swipe/drag |
showCreatedAt | false | Show a timestamp badge on the toast |
createdAtFormatter | locale time | Function formatting the timestamp (see below) |
alignment | "left" | Text direction inside the toast body |
progressAlignment | "right-to-left" | Progress animation direction |
offset | "16px" | Distance from viewport edge |
gap | "8px" | Gap between toasts |
width | "350px" | Default toast width |
zIndex | 9999 | Root container z-index |
Per-Toast Only Options
These are available on show, typed helpers, and update — not in global config:
| Option | What it does |
|---|---|
theme | CSS accent class, e.g. "brand" → tf-toast-accent--brand |
css | Inline CSS variable overrides (bg, color, accentColor, …) |
Example
import { createToastflow } from "vue-toastflow";
app.use(
createToastflow({
position: "top-right",
duration: 5000,
maxVisible: 4,
queue: true,
pauseStrategy: "resume",
preventDuplicates: true,
}),
);
toast.warning({
title: "Server maintenance",
position: "bottom-center",
duration: 15000,
closeOnClick: true,
buttons: {
alignment: "bottom-right",
buttons: [{ label: "Dismiss" }],
},
});
Animation Class Names
Override globally or per-toast:
createToastflow({
animation: {
name: "MyToastMotion",
bump: "MyToastBump",
clearAll: "MyToastClearAll",
update: "MyToastUpdate",
},
});
Defaults: Toastflow__animation, Toastflow__animation-bump, Toastflow__animation-clearAll, Toastflow__animation-update.
Timestamps
showCreatedAt: true renders a small badge with the time the toast was created. The default format is the locale time; pass createdAtFormatter to change it:
createToastflow({
showCreatedAt: true,
createdAtFormatter: (createdAt) =>
new Date(createdAt).toLocaleTimeString([], {
hour: "2-digit",
minute: "2-digit",
}),
});
createdAtFormatter is a function, so in Nuxt it cannot live in nuxt.config (config is JSON-serialized). Configure it at runtime instead — see Nuxt notes.Buttons Config
toast.info({
title: "Changes saved",
buttons: {
alignment: "bottom-right",
layout: "row",
buttons: [
{
label: "Undo",
onClick(ctx) {
console.log("Undo", ctx.id);
},
},
],
},
});
Each button supports label or html, plus optional id, ariaLabel, className, dismissOnClick (dismiss before onClick runs), dismissAfterClick (dismiss after onClick runs), and onClick(ctx, event).
html buttons are rendered without sanitization — pass trusted markup only, or sanitize it yourself. Set ariaLabel on html buttons so screen readers can announce them.ToastButtonsConfig for the complete shape.