API
Configuration
Full Toastflow configuration reference covering global defaults, per-toast overrides, and the option resolution order across Vue and Nuxt.
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.
Full TypeScript definitions:
packages/core/src/types.ts. The reference below covers the most common options.Layout & Position
position
ToastPosition
Viewport anchor for the stack. Default:
"top-right".alignment
"left" | "center" | "right"
Text direction inside the toast body. Default:
"left".offset
string
Distance from the viewport edge. Default:
"16px".gap
string
Gap between toasts. Default:
"8px".width
string
Default toast width. Default:
"350px".zIndex
number
Root container z-index. Default:
9999.overflowScroll
boolean
Scroll the stack when it grows taller than the viewport. Default:
false.containerId
string
Target a specific
<ToastContainer id> (details). No default.Timing & Progress
duration
number
Auto-dismiss delay in ms. Default:
5000. Infinity / 0 = no auto-dismiss.pauseOnHover
boolean
Pause the timer on hover or touch. Default:
true.pauseStrategy
"resume" | "reset"
"resume" continues the remaining time, "reset" restarts the full duration. Default: "resume".progressBar
boolean
Show a progress bar for finite durations. Default:
true.progressAlignment
"right-to-left" | "left-to-right"
Progress animation direction. Default:
"right-to-left".showCreatedAt
boolean
Show a timestamp badge on the toast. Default:
false.createdAtFormatter
(createdAt: number) => string
Function formatting the timestamp (see below). Default: locale time.
Stacking & Queue
maxVisible
number
Max visible toasts per position. Default:
5. <= 0 = no cap.queue
boolean
Queue overflowed toasts instead of evicting. Default:
false.order
"newest" | "oldest"
Insert order and eviction target. Default:
"newest".preventDuplicates
boolean
De-duplicate by container + position + type + title + description. Default:
false.Interaction
closeButton
boolean
Show the floating close button. Default:
true.closeOnClick
boolean
Dismiss on body click. Default:
false.swipeToDismiss
boolean
Dismiss with a right swipe/drag. Default:
false.Content & Appearance
showIcon
boolean
Show the type icon. Default:
true.supportHtml
boolean
Allow HTML in title and description — use trusted content only. Default:
false.sanitizer
(html: string) => string
Hook sanitizing HTML before render, e.g. DOMPurify (details). No default.
css
ToastCSSOverrides
CSS variable overrides (
bg, color, accentColor, …). Works globally and per-toast — per-toast values merge over the global ones (details). No default.Per-Toast Only Options
Available on show, typed helpers, and update — not in global config:
theme
string
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:
animation-config.ts
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:
created-at-formatter.ts
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
buttons-config.ts
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.Full button types: see
ToastButtonsConfig for the complete shape.