# Overview

One toast runtime, three entry points. Pick the package that matches your app and keep the same mental model everywhere.

:docs-npm-badges{packages="vue-toastflow:43b883,nuxt-toastflow:02a361,toastflow-core:64748b"}

::card-group
  :::card
  ---
  icon: i-simple-icons-vuedotjs
  title: Vue
  to: https://www.toastflow.top/docs/vue/quick-start
  ---
  `vue-toastflow`

   — Plugin + components for any Vue 3 app.
  :::

  :::card
  ---
  icon: i-simple-icons-nuxtdotjs
  title: Nuxt
  to: https://www.toastflow.top/docs/nuxt/quick-start
  ---
  `nuxt-toastflow`

   — Zero-config module with auto-imports and SSR.
  :::

  :::card
  ---
  icon: i-tabler-automation
  title: Core
  to: https://www.toastflow.top/docs/headless/core-store
  ---
  `toastflow-core`

   — Framework-agnostic store. Bring your own renderer.
  :::
::

## Package Map

::code-tree{expand-all default-value="vue/main.ts"}
```ts [vue/main.ts]
import { createApp } from "vue";
import { createToastflow } from "vue-toastflow";
import App from "./App.vue";

createApp(App).use(createToastflow()).mount("#app");
```

```vue [vue/App.vue]
<script setup lang="ts">
import { ToastContainer, toast } from "vue-toastflow";

function onSave() {
  toast.success({ title: "Saved", description: "Your changes are live." });
}
</script>

<template>
  <ToastContainer />
  <button @click="onSave">Save</button>
</template>
```

```ts [nuxt/nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["nuxt-toastflow"],
  toastflow: {
    config: { position: "top-right", duration: 5000 },
  },
});
```

```vue [nuxt/app.vue]
<script setup lang="ts">
function onSave() {
  // `toast` and `ToastContainer` are auto-imported
  toast.success({ title: "Saved", description: "Your changes are live." });
}
</script>

<template>
  <ToastContainer />
  <button @click="onSave">Save</button>
</template>
```

```ts [headless/store.ts]
import { createToastStore } from "toastflow-core";

export const toastStore = createToastStore({
  position: "top-right",
  duration: 5000,
});

toastStore.subscribe((state) => {
  // Render `state.toasts` with your own UI.
});

toastStore.show({ type: "success", title: "Saved" });
```
::

## Shared Runtime

::steps
### Create

Use a payload object, a title + options call, or a typed helper like `toast.success(...)`.

### Update

Keep the returned id when you want to turn a loading toast into a success or error toast.

### Control

Pause the queue, dismiss all toasts, subscribe to state, or listen to lifecycle events.
::

::code-group
```ts [basic.ts]
toast.success({
  title: "Saved",
  description: "Your changes are live.",
});
```

```ts [loading.ts]
const request = toast.loading(fetch("/api/save"), {
  loading: { title: "Saving" },
  success: { title: "Saved" },
  error: { title: "Failed" },
});

await request;
```

```ts [store.ts]
toast.dismissAll();
toast.pauseQueue();
toast.resumeQueue();

toast.subscribe((state) => {
  console.log(state.toasts.length);
});
```
::

## Live Runtime

::docs-live-example
## What Is Covered

  :::card-group
    ::::card
    ---
    icon: i-tabler-package
    title: Install paths
    to: https://www.toastflow.top/docs/vue/quick-start
    ---
    Vue plugin setup, Nuxt module setup, and the headless core entry point.
    ::::

    ::::card
    ---
    icon: i-tabler-stopwatch
    title: Runtime behavior
    to: https://www.toastflow.top/docs/vue/timers-and-progress
    ---
    Timers, progress bars, queue behavior, duplicate prevention, and loading flows.
    ::::

    ::::card
    ---
    icon: i-tabler-file-code-2
    title: API surface
    to: https://www.toastflow.top/docs/api/runtime-exports
    ---
    Shared exports, typed actions, state, events, config, and core utilities.
    ::::

    ::::card
    ---
    icon: i-tabler-palette
    title: Customization
    to: https://www.toastflow.top/docs/global/styling
    ---
    CSS variables, theme classes, inline overrides, shipped CSS control, and headless rendering.
    ::::
  :::

## Practical Rules

  :::accordion
    ::::accordion-item{label="Where should I start?"}
    Use Vue quick start for Vue apps, Nuxt quick start for Nuxt apps, and Headless only when you need to render everything yourself.
    ::::

    ::::accordion-item{label="Do Vue and Nuxt use different toast APIs?"}
    No. Nuxt adds module wiring and auto-imports, but 

    `toast.show`

    , 

    `toast.success`

    , 

    `toast.loading`

    , 

    `toast.update`

    , and store controls behave the same.
    ::::

    ::::accordion-item{label="When should I use headless mode?"}
    Use it when Toastflow's default card is not enough. In Vue, try the headless slot first. Outside Vue, use 

    `toastflow-core`

    .
    ::::

    ::::accordion-item{label="Where is the API reference?"}
    See 

    [Configuration](https://www.toastflow.top/docs/api/configuration)

    , 

    [Actions](https://www.toastflow.top/docs/api/actions)

    , 

    [Events](https://www.toastflow.top/docs/api/events)

    , and 

    [State](https://www.toastflow.top/docs/api/state)

    .
    ::::
  :::
::


# Styling

Toastflow is CSS-first. Start with variables, use theme classes for reusable variants, and keep inline `css` for one-off toasts.

::tip
Most apps only need CSS variables. You do not need a design-system wrapper just to make Toastflow match your brand.
::

## The Three Levels

::tabs
  :::tabs-item{label="Global variables"}
  Use this for the default app-wide look.

  ```ts [toast.ts]
  toast.info({
    title: "Global variables",
    description: "Font, radius, and color tokens from :root.",
  });
  ```

  ```css [app.css]
  :root {
    --tf-toast-font-family:
      "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
    --tf-toast-border-radius: 4px;
    --tf-toast-padding: 18px;
    --tf-toast-bg: #fff7ed;
    --tf-toast-color: #431407;
    --tf-toast-title-color: #431407;
    --tf-toast-description-color: #7c2d12;
    --tf-toast-border-color: #fb923c;
    --tf-toast-icon-color: #ea580c;
    --tf-toast-progress-bg: color-mix(in srgb, #ea580c 18%, transparent);
    --tf-toast-progress-bar-bg: #ea580c;
  }
  ```
  :::

  :::tabs-item{label="Theme class"}
  Use this when a toast should opt into a named visual style.

  `theme: "brand"` maps to `.tf-toast-accent--brand`. If you pass a full class name that already starts with `tf-toast-accent--`, Toastflow uses it as-is.

  ```ts [toast.ts]
  toast.info({
    title: "Release",
    description: "v1.0.0 is out.",
    theme: "brand",
  });
  ```

  ```css [app.css]
  .tf-toast-accent--brand {
    --tf-toast-bg: #ecfeff;
    --tf-toast-color: #164e63;
    --tf-toast-border-color: #67e8f9;
    --tf-toast-title-color: #0e7490;
    --tf-toast-description-color: #155e75;
    --tf-toast-progress-bg: color-mix(in srgb, #0891b2 20%, transparent);
    --tf-toast-progress-bar-bg: #0891b2;
    --tf-toast-icon-color: #0891b2;
  }
  ```
  :::

  :::tabs-item{label="Inline override"}
  Use this only for one-off cases generated from runtime data.

  ```ts [toast.ts]
  toast.custom({
    title: "Runtime accent",
    description: "One-off color override, inherited global structure.",
    css: {
      bg: "#450a0a",
      color: "#fff1f2",
      titleColor: "#ffe4e6",
      descriptionColor: "#fecdd3",
      borderColor: "#fb7185",
      iconColor: "#fbbf24",
      progressBg: "color-mix(in srgb, #fbbf24 20%, transparent)",
      progressBarBg: "#fbbf24",
    },
  });
  ```
  :::
::

The live preview below mirrors all three tabs. It scopes the global variables around a local preview container, so **Theme class** and **Inline override** inherit the global font, radius, and spacing while overriding only their own color tokens.

::docs-toast-preview{variant="styling"}
## Common Variables

| Variable                       | Controls            |
| ------------------------------ | ------------------- |
| `--tf-toast-bg`                | Toast background    |
| `--tf-toast-color`             | Title and main text |
| `--tf-toast-description-color` | Description text    |
| `--tf-toast-border-color`      | Card border         |
| `--tf-toast-border-radius`     | Card radius         |
| `--tf-toast-font-family`       | Card typography     |
| `--tf-toast-padding`           | Card padding        |
| `--tf-toast-progress-bar-bg`   | Progress bar fill   |
| `--tf-toast-progress-bg`       | Progress track      |
| `--tf-toast-icon-color`        | Current toast icon  |
| `--tf-toast-icon-success`      | Success icon color  |
| `--tf-toast-icon-error`        | Error icon color    |

## Disable Shipped CSS

Disable the packaged stylesheet when you want to own every Toastflow CSS variable yourself. The setup is different for Nuxt and plain Vue.

  :::code-tree{expand-all default-value="nuxt/nuxt.config.ts"}
  ```ts [nuxt/nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    css: ["~/assets/toastflow.css"],
    toastflow: {
      css: false,
    },
  });
  ```

  ```css [nuxt/assets/toastflow.css]
  :root {
    --tf-toast-font-family:
      "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
    --tf-toast-border-radius: 4px;
    --tf-toast-padding: 18px;
    --tf-toast-bg: #fff7ed;
    --tf-toast-color: #431407;
    --tf-toast-border-color: #fb923c;
    --tf-toast-icon-color: #ea580c;
  }
  ```

  ```ts [vue/src/main.ts]
  import { createApp } from "vue";
  import { createToastflow } from "vue-toastflow";
  import "./toastflow.css";

  createApp(App)
    .use(createToastflow({}, { css: false }))
    .mount("#app");
  ```

  ```css [vue/src/toastflow.css]
  :root {
    --tf-toast-font-family:
      "IBM Plex Mono", "SFMono-Regular", Consolas, monospace;
    --tf-toast-border-radius: 4px;
    --tf-toast-padding: 18px;
    --tf-toast-bg: #fff7ed;
    --tf-toast-color: #431407;
    --tf-toast-border-color: #fb923c;
    --tf-toast-icon-color: #ea580c;
  }
  ```
  :::

## Color Override Priority

When multiple layers set the same color, Toastflow resolves in this order:

1. **Per-toast `css` prop** (inline style)
2. **Per-toast `theme` class** (`.tf-toast-accent--brand`)
3. **Global override** (`--tf-toast-bg` on `:root`)
4. **Built-in type/default preset** (`success`, `error`, `custom`, ...)

`--tf-toast-color` cascades to title and description colors unless `--tf-toast-title-color` or `--tf-toast-description-color` is explicitly set.

## Tailwind CSS v4

Use `@layer base` to override Toastflow tokens in Tailwind v4:

```css [app.css]
@layer base {
  :root {
    --tf-toast-bg: var(--color-background-subtle);
    --tf-toast-color: var(--color-foreground);
    --tf-toast-border-color: var(--color-border);
    --tf-toast-border-radius: var(--radius-lg);
    --tf-toast-font-family: var(--font-sans);
  }
}
```

  :::warning
  `@theme`

   will not work — Tailwind wraps 

  `@theme`

   in 

  `@layer theme`

  , which has lower priority than Toastflow's unlayered styles.
  :::

## More Variable Groups

| Group              | Examples                                                                |
| ------------------ | ----------------------------------------------------------------------- |
| **Layout**         | `--tf-toast-padding`, `--tf-toast-gap`, `--tf-toast-border-radius`      |
| **Stack**          | `--tf-toast-stack-padding-top`, `--tf-toast-stack-padding-right`        |
| **Typography**     | `--tf-toast-title-font-size`, `--tf-toast-description-line-height`      |
| **Close button**   | `--tf-toast-close-size`, `--tf-toast-close-icon-size`                   |
| **Action buttons** | `--tf-toast-button-*`                                                   |
| **Progress**       | `--tf-toast-progress-height`, `--tf-toast-progress-duration`            |
| **Motion**         | `--tf-toast-animation-in-duration`, `--tf-toast-animation-out-duration` |
| **Shorthands**     | `--tf-toast-accent-color`, `--tf-toast-icon-color`                      |

  :::note
  **Full variable reference:**

   every variable and its default lives in 

  [`packages/vue/src/styles.css`](https://github.com/adrianjanocko/toastflow/blob/main/packages/vue/src/styles.css){rel=""nofollow"" target="\_blank"}

   — the 

  `:root`

   block is the source of truth.
  :::

## The `accentColor` Shorthand

In the per-toast `css` prop, `accentColor` sets the text, title, description, and progress bar colors at once:

```ts [accent-color.ts]
toast.custom({
  title: "One color, four tokens",
  css: {
    accentColor: "#0891b2",
  },
});
```

## HTML Support

`supportHtml: true` enables HTML in `title` and `description`:

```ts [html-support.ts]
toast.info({
  title: "<strong>Release</strong>",
  description: 'Read <a href="/changelog">changelog</a>',
  supportHtml: true,
});
```

  :::caution
  Toastflow does not sanitize HTML by default — this applies to 

  `supportHtml`

   content 

  **and**

   

  `html`

   buttons. Rendering untrusted input (user submissions, API error messages, URL params) this way is an XSS vector. Configure the 

  `sanitizer`

   hook below, sanitize the content yourself before passing it in, or keep 

  `supportHtml`

   off.
  :::

### Sanitizer Hook

Set `sanitizer` once in the global config and every HTML render (`supportHtml` titles/descriptions and `html` buttons) goes through it:

```ts [sanitizer.ts]
import DOMPurify from "dompurify";

app.use(
  createToastflow({
    supportHtml: true,
    sanitizer: (html) => DOMPurify.sanitize(html),
  }),
);
```

The hook receives the raw HTML string and returns the sanitized string. If it throws, the content is dropped instead of rendered raw. Like any other option, it can be overridden per toast.

  :::note
  In Nuxt, 

  `sanitizer`

   is a function and cannot live in 

  `nuxt.config`

   (config is JSON-serialized). Configure it in a client plugin instead — see 

  [Nuxt Notes](https://www.toastflow.top/docs/nuxt/nuxt-notes)

  .
  :::

## When CSS Is Not Enough

  :::card-group
    ::::card
    ---
    icon: i-tabler-template
    title: Headless slot
    to: https://www.toastflow.top/docs/headless/headless-slot
    ---
    Keep the Vue store and accessibility helpers, but render your own toast card.
    ::::

    ::::card
    ---
    icon: i-tabler-automation
    title: Core store
    to: https://www.toastflow.top/docs/headless/core-store
    ---
    Use the framework-agnostic store and build your renderer from scratch.
    ::::
  :::
::


# Vue Quick Start

::docs-npm-badges{downloads packages="vue-toastflow:43b883"}
::

Use `vue-toastflow` when you have a normal Vue app entry file.

::steps
### Install

  :::code-group
  ```bash [pnpm]
  pnpm add vue-toastflow
  ```

  ```bash [npm]
  npm install vue-toastflow
  ```

  ```bash [yarn]
  yarn add vue-toastflow
  ```
  :::

### Register the plugin

```ts [main.ts]
import { createApp } from "vue";
import App from "./App.vue";
import { createToastflow } from "vue-toastflow";

createApp(App).use(createToastflow()).mount("#app");
```

### Render one container

```vue [App.vue]
<script setup lang="ts">
import { ToastContainer } from "vue-toastflow";
</script>

<template>
  <ToastContainer />
  <RouterView />
</template>
```

### Fire a toast

```ts [save.ts]
import { toast } from "vue-toastflow";

toast.success({
  title: "Saved",
  description: "Your changes are live.",
});
```
::

::warning
`toast.*`

 needs the plugin-created store. Install 

`createToastflow()`

 before calling toasts from stores, services, or composables.
::

## Minimal File Tree

::code-tree{expand-all default-value="src/main.ts"}
```ts [src/main.ts]
import { createApp } from "vue";
import App from "./App.vue";
import { createToastflow } from "vue-toastflow";

createApp(App).use(createToastflow()).mount("#app");
```

```vue [src/App.vue]
<script setup lang="ts">
import { ToastContainer } from "vue-toastflow";
import ProfileForm from "./components/ProfileForm.vue";
</script>

<template>
  <ToastContainer />
  <ProfileForm />
</template>
```

```vue [src/components/ProfileForm.vue]
<script setup lang="ts">
import { ref } from "vue";
import { saveProfile } from "../features/save";

const isSaving = ref(false);

async function onSubmit() {
  if (isSaving.value) {
    return;
  }

  isSaving.value = true;
  try {
    await saveProfile();
  } finally {
    isSaving.value = false;
  }
}
</script>

<template>
  <form @submit.prevent="onSubmit">
    <button type="submit" :disabled="isSaving">
      {{ isSaving ? "Saving..." : "Save profile" }}
    </button>
  </form>
</template>
```

```ts [src/features/save.ts]
import { toast } from "vue-toastflow";

export async function saveProfile() {
  await toast.loading(fetch("/api/profile"), {
    loading: { title: "Saving profile" },
    success: { title: "Profile saved" },
    error: { title: "Save failed" },
  });
}
```
::

## Next Steps

::card-group
  :::card
  ---
  icon: i-tabler-bell
  title: Toasts
  to: https://www.toastflow.top/docs/vue/toasts
  ---
  Types, create call styles, per-toast overrides, positions, duplicates, and lifecycle hooks.
  :::

  :::card
  ---
  icon: i-tabler-stopwatch
  title: Timers & Progress
  to: https://www.toastflow.top/docs/vue/timers-and-progress
  ---
  Duration rules, pause strategies, queue behavior, and the loading helper.
  :::

  :::card
  ---
  icon: i-tabler-hand-click
  title: Buttons & Actions
  to: https://www.toastflow.top/docs/vue/buttons-and-actions
  ---
  Action buttons, close behavior, and timestamps.
  :::

  :::card
  ---
  icon: i-tabler-palette
  title: Styling
  to: https://www.toastflow.top/docs/global/styling
  ---
  Override variables, create theme variants, or disable shipped CSS.
  :::

  :::card
  ---
  icon: i-tabler-player-play
  title: Live examples
  to: https://www.toastflow.top/docs/examples/live-examples
  ---
  Try 

  `show`

  , typed helpers, loading toasts, updates, and store controls in the browser.
  :::

  :::card
  ---
  icon: i-tabler-package
  title: Runtime exports
  to: https://www.toastflow.top/docs/api/runtime-exports
  ---
  Components, 

  `toast`

  , types, and core utilities exported by 

  `vue-toastflow`

  .
  :::
::


# Toasts

This page covers the toast payload model and how show, update, and dismiss work.

## Types

Toastflow supports seven toast types:

::card-group
  :::card{icon="i-tabler-loader-2" title="loading"}
  Async work in progress. Progress bar is disabled, duration is infinite.
  :::

  :::card{icon="i-tabler-help-circle" title="default"}
  Neutral notification without a specific semantic.
  :::

  :::card{icon="i-tabler-circle-check" title="success"}
  Positive outcome confirmation.
  :::

  :::card{icon="i-tabler-circle-x" title="error"}
  Failure or critical issue.
  :::

  :::card{icon="i-tabler-info-circle" title="info"}
  Informational message.
  :::

  :::card{icon="i-tabler-alert-triangle" title="warning"}
  Warning that requires attention.
  :::

  :::card{icon="i-tabler-sparkles" title="custom"}
  No preset colors. Use with 

  `theme`

   or 

  `css`

   for fully branded toasts.
  :::
::

## Create Toasts

Use the call style that makes the content clearest at the call site.

::code-group
```ts [payload-object.ts]
toast.show({
  type: "success",
  title: "Saved",
  description: "Done",
});
```

```ts [title-options.ts]
toast.show("Saved", {
  type: "success",
  description: "Done",
});
```

```ts [typed-helper.ts]
toast.success({
  title: "Saved",
  description: "Done",
});
```
::

::docs-toast-preview{variant="create"}
  :::warning
  `title`

   or 

  `description`

   must be non-empty. Passing both as empty strings throws.
  :::

## Per-Toast Overrides

Any global config field can be overridden on a single toast:

```ts [per-toast-override.ts]
toast.info({
  title: "Maintenance",
  description: "At 22:00 UTC",
  position: "bottom-center",
  duration: 15000,
  closeOnClick: true,
  progressAlignment: "left-to-right",
});
```

See the full option list on the [Configuration](https://www.toastflow.top/docs/api/configuration) page.

## Positions

| Position        | Anchor                     |
| --------------- | -------------------------- |
| `top-left`      | Top-left corner            |
| `top-center`    | Top center                 |
| `top-right`     | Top-right corner (default) |
| `bottom-left`   | Bottom-left corner         |
| `bottom-center` | Bottom center              |
| `bottom-right`  | Bottom-right corner        |

## Ordering

`order` controls how new toasts are inserted and which toast gets evicted when the stack is full.

- **`newest`** (default) — newest toast on top, oldest evicted first
- **`oldest`** — oldest toast on top, newest evicted first

## Overflow Scroll

With `overflowScroll: true`, a stack taller than the viewport becomes scrollable (with a thin themed scrollbar) instead of overflowing off-screen. Works for every position; bottom stacks stay pinned to the newest toast unless you scroll away. Scrollbar colors are themable via the [`--tf-toast-scrollbar-*` variables](https://www.toastflow.top/docs/global/styling).

```ts [overflow-scroll.ts]
createToastflow({ overflowScroll: true });
```

## Duplicate Prevention

Enable `preventDuplicates: true` to avoid re-adding identical toasts. Matching uses `position`, `containerId`, `type`, `title`, and `description`.

When a duplicate is found:

  :::steps
  ### Existing toast updated

  New incoming overrides are merged into the existing toast.

  ### Id reused

  The original toast id is kept.

  ### Timer restarted

  Visible toast timer restarts with the configured duration.

  ### Event emitted

  A `duplicate` event fires via `subscribeEvents`.
  :::

## Update and Dismiss

```ts [update-and-dismiss.ts]
const id = toast.warning({
  title: "Low disk space",
  description: "Only 1 GB left",
});

toast.update(id, {
  title: "Disk space restored",
  type: "success",
});

toast.dismiss(id);
toast.dismissAll();
```

With multiple containers, `dismissAll` accepts a `{ containerId }` filter — see [Multiple containers](https://www.toastflow.top/docs/vue/multiple-containers).

## Dismiss Interactions

Besides the close button and the programmatic API, users can dismiss toasts directly:

| Interaction    | Option                 | Default | Behavior                                                                                                       |
| -------------- | ---------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| Click anywhere | `closeOnClick: true`   | `false` | Clicking the toast body dismisses it. Buttons and links inside the toast still work normally.                  |
| Swipe right    | `swipeToDismiss: true` | `false` | Drag the toast to the right (pointer or touch). Past \~35% of its width it dismisses; otherwise it snaps back. |
| Escape key     | always on              | —       | Pressing `Escape` while focus is inside the toast (e.g. on a button) dismisses it.                             |

```ts [swipe-to-dismiss.ts]
toast.info("Swipe me away", {
  swipeToDismiss: true,
});
```

Swiping starts only after a small horizontal movement, so vertical scrolling on touch devices is not hijacked, and it never starts on interactive elements (buttons, links, inputs).

## Lifecycle Hooks

Set globally or per toast:

  :::field-group
    ::::field{name="onMount" type="(ctx) => void"}
    After the toast enters state.
    ::::

    ::::field{name="onUnmount" type="(ctx) => void"}
    After the toast is removed from state.
    ::::

    ::::field{name="onClick" type="(ctx, event) => void"}
    When the toast body is clicked.
    ::::

    ::::field{name="onClose" type="(ctx) => void"}
    Right before the leaving phase starts.
    ::::
  :::

Each hook receives a context object with `id`, `position`, `type`, `title`, `description`, `createdAt`, and `containerId` (when set).

## Accessibility

Accessible behavior works out of the box — nothing to configure:

- `error` and `warning` toasts render with `role="alert"` and `aria-live="assertive"`; all other types use `role="status"` and `aria-live="polite"`.
- Every toast gets an `aria-label` built from its title, description, and timestamp — HTML markup is stripped, so screen readers only hear text.
- The close button is a real `<button>` with an `aria-label`, and `Escape` dismisses the focused toast.
- When a dismissed toast held keyboard focus, focus moves to the nearest remaining toast instead of dropping back to the page.
- All animations respect `prefers-reduced-motion` and fall back to instant transitions.
::


# Timers & Progress

Timer behavior is deterministic and controlled by `duration`, `pauseOnHover`, and `pauseStrategy`.

## Duration Rules

| Value        | Behavior                                |
| ------------ | --------------------------------------- |
| Finite `> 0` | Auto-dismiss scheduled                  |
| `Infinity`   | No auto-dismiss                         |
| `0`          | No auto-dismiss (treated as non-finite) |

When duration is not finite, the progress bar is automatically disabled.

## Progress Bar

Enable with `progressBar: true` (default). Only renders when duration is finite.

```ts [progress-bar.ts]
toast.info({
  title: "Uploading",
  duration: 8000,
  progressBar: true,
  progressAlignment: "left-to-right",
});
```

Alignment options: `right-to-left` (default) or `left-to-right`.

::docs-toast-preview{variant="timers"}
## Pause on Hover

With `pauseOnHover: true`, hover and touch interactions pause the timer. On leave, the `pauseStrategy` decides what happens:

  :::tabs
    ::::tabs-item{label="resume"}
    Continue with remaining time. This is the default.

    ```ts [pause-resume.ts]
    createToastflow({
      pauseOnHover: true,
      pauseStrategy: "resume",
    });
    ```
    ::::

    ::::tabs-item{label="reset"}
    Restart the full duration and emit a `timer-reset` event.

    ```ts [pause-reset.ts]
    createToastflow({
      pauseOnHover: true,
      pauseStrategy: "reset",
    });
    ```
    ::::
  :::

## Manual Pause & Resume

```ts [manual-pause.ts]
const id = toast.info({
  title: "Session expires soon",
  duration: 10000,
});

toast.pause(id);
toast.resume(id);
```

## Queue & Capacity

Queue behavior depends on `maxVisible` and `queue`:

  :::accordion
    ::::accordion-item{label="queue: false (default)"}
    When the stack is full, one visible toast is evicted by the 

    `order`

     strategy to make room.
    ::::

    ::::accordion-item{label="queue: true"}
    Overflow toasts are queued and shown later when a slot opens. The queue is managed per container + position.
    ::::
  :::

```ts [queue-controls.ts]
toast.pauseQueue();
toast.resumeQueue();
```

## Loading Helper

Wraps an async operation and transitions a single toast through loading -> success / error:

```ts [loading-helper.ts]
const result = toast.loading(() => fetch("/api/import").then((r) => r.json()), {
  loading: { title: "Importing", description: "Processing file" },
  success: (data) => ({
    title: "Import complete",
    description: `${data.count} records saved`,
    duration: 6000,
  }),
  error: (err) => ({
    title: "Import failed",
    description: err instanceof Error ? err.message : "Unknown error",
    duration: 10000,
  }),
});

await result;
console.log(result.toastId);
```

The core guards against stale async runs with an internal token per loading toast id.

:docs-toast-preview{variant="import"}
::


# Buttons & Actions

Add inline action buttons through the `buttons` config.

## Basic Button Group

```ts [action-button.ts]
toast.info({
  title: "File archived",
  description: "Use an action when the user can recover immediately.",
  buttons: {
    alignment: "bottom-right",
    buttons: [
      {
        id: "undo",
        label: "Undo",
        dismissAfterClick: true,
        onClick() {
          toast.success({ title: "Restored" });
        },
      },
    ],
  },
});
```

::docs-toast-preview{variant="buttons"}
## Button Alignment

| Value          | Position                       |
| -------------- | ------------------------------ |
| `top-left`     | Above content, left            |
| `top-right`    | Above content, right           |
| `center-left`  | Beside content, left           |
| `center-right` | Beside content, right          |
| `bottom-left`  | Below content, left            |
| `bottom-right` | Below content, right (default) |

## Layout Direction

  :::tabs
    ::::tabs-item{label="row (default)"}
    Action group sits side-by-side with the toast content.

    ```ts [layout-row.ts]
    toast.info({
      title: "Release 1.2.0",
      buttons: {
        layout: "row",
        buttons: [{ label: "Open changelog" }],
      },
    });
    ```
    ::::

    ::::tabs-item{label="column"}
    Action group takes a dedicated row above or below content.

    ```ts [layout-column.ts]
    toast.info({
      title: "Release 1.2.0",
      buttons: {
        layout: "column",
        buttons: [{ label: "Open changelog" }, { label: "Remind me later" }],
      },
    });
    ```
    ::::
  :::

## Each Button

Each button supports:

  :::field-group
    ::::field{name="label" type="string"}
    Plain text label.
    ::::

    ::::field{name="html" type="string"}
    HTML string (requires 

    `supportHtml`

     on the toast).
    ::::

    ::::field{name="id" type="string"}
    Unique identifier.
    ::::

    ::::field{name="ariaLabel" type="string"}
    Accessible label.
    ::::

    ::::field{name="className" type="string"}
    Custom CSS class.
    ::::

    ::::field{name="dismissOnClick" type="boolean"}
    Dismiss the toast before 

    `onClick`

     runs.
    ::::

    ::::field{name="dismissAfterClick" type="boolean"}
    Dismiss the toast after 

    `onClick`

     runs.
    ::::

    ::::field{name="onClick" type="(ctx, event) => void"}
    Click handler.
    ::::
  :::

  :::caution
  `html`

   buttons are rendered without sanitization — pass trusted markup only, or configure the 

  [`sanitizer` hook](https://www.toastflow.top/docs/global/styling#sanitizer-hook)

  . Set 

  `ariaLabel`

   on 

  `html`

   buttons so screen readers can announce them.
  :::

## Close Interactions

  :::field-group
    ::::field{name="closeButton" type="boolean"}
    Show or hide the floating close icon.
    ::::

    ::::field{name="closeOnClick" type="boolean"}
    Dismiss on toast body click.
    ::::

    ::::field{name="onClick" type="(ctx, event) => void"}
    Custom body click callback.
    ::::

    ::::field{name="onClose" type="(ctx) => void"}
    Callback fired before the leaving phase.
    ::::
  :::

```ts [close-interactions.ts]
toast.warning({
  title: "Action required",
  closeOnClick: true,
  onClick(ctx) {
    console.log("Clicked", ctx.id);
  },
  onClose(ctx) {
    console.log("Closing", ctx.id);
  },
});
```

## Created-At Badge

Show a timestamp on the toast:

```ts [created-at.ts]
toast.default({
  title: "Background sync",
  showCreatedAt: true,
  createdAtFormatter(ts) {
    return new Date(ts).toLocaleTimeString();
  },
});
```

If the formatter throws or is missing, Toastflow falls back to its default time formatter.
::


# Multiple Containers

By default you mount a single `<ToastContainer />` and every toast renders in it. Optionally, you can mount several containers — each with its own `id` — and route individual toasts to them.

## Setup

::steps
### Mount the containers

Give each extra container an `id`; the one without an `id` stays the default:

```vue [App.vue]
<template>
  <!-- default container: receives toasts without a containerId -->
  <ToastContainer />

  <!-- named container -->
  <ToastContainer id="panel" />
</template>
```

### Route toasts to a container

Target a container with the `containerId` option (any show helper, `update`, and global config accept it):

```ts [routing.ts]
toast.success("Saved"); // → default container
toast.success("Saved", { containerId: "panel" }); // → <ToastContainer id="panel" />
```
::

::note
The component prop is 

`id`

, the toast option is 

`containerId`

 — the toast option can't be called 

`id`

 because that's the toast's own identifier.
::

## Behavior

- Matching is strict: toasts without a `containerId` render only in the container without an `id`, and vice versa.
- `maxVisible`, `queue`, ordering, and `preventDuplicates` are all scoped per **container + position** — a full stack in one container never evicts or queues toasts in another.
- `dismiss(id)`, `update(id, ...)`, `pause(id)`, and `resume(id)` work by toast id regardless of container.
- `dismissAll()` clears everything; pass a filter to scope it:

```ts [dismiss-scoped.ts]
toast.dismissAll({ containerId: "panel" }); // only container "panel"
toast.dismissAll({ containerId: undefined }); // only the default container
toast.dismissAll(); // everything
```

## Live Example

::docs-multi-container-example
## Warnings

  :::warning
  In case of a misconfiguration, Toastflow logs a one-shot console warning when a toast targets a 

  `containerId`

   with no matching mounted 

  `<ToastContainer id>`

  , or when two containers are mounted with the same 

  `id`

   (each renders the same toasts twice).
  :::

## Nuxt

The auto-registered `<ToastContainer>` component supports the same `id` prop — mount as many as you need, no extra module configuration required.
::


# Nuxt Quick Start

::docs-npm-badges{downloads packages="nuxt-toastflow:02a361"}
::

Use `nuxt-toastflow` for Nuxt 3 and Nuxt 4 apps. The module wires the plugin, CSS, auto-imports, component registration, and the same runtime exports available from `vue-toastflow`.

::steps
### Install

  :::code-group
  ```bash [pnpm]
  pnpm add nuxt-toastflow
  ```

  ```bash [npm]
  npm install nuxt-toastflow
  ```

  ```bash [yarn]
  yarn add nuxt-toastflow
  ```
  :::

### Enable the module

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["nuxt-toastflow"],
  toastflow: {
    config: {
      position: "top-right",
      duration: 5000,
      maxVisible: 5,
    },
  },
});
```

### Render the container once

```vue [app.vue]
<template>
  <ToastContainer />
  <NuxtPage />
</template>
```

One container is the default setup. You can also mount additional `<ToastContainer id="...">` instances and route toasts to them with the `containerId` option — see [Multiple Containers](https://www.toastflow.top/docs/vue/multiple-containers).

### Use `toast` or `useToast()`

```vue [pages/index.vue]
<script setup lang="ts">
toast.success({
  title: "Saved",
  description: "Your changes are live.",
});

const toastApi = useToast();

toastApi.info({
  title: "useToast() works too",
});
</script>
```
::

::warning
Use 

`toast`

 and 

`useToast()`

 from client-side execution: click handlers, 

`onMounted`

, client composables, and UI callbacks. Do not call them from Nitro handlers.
::

## Minimal File Tree

::code-tree{expand-all default-value="nuxt.config.ts"}
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["nuxt-toastflow"],
  toastflow: {
    config: {
      position: "top-right",
      queue: true,
    },
  },
});
```

```vue [app.vue]
<template>
  <ToastContainer />
  <NuxtPage />
</template>
```

```vue [pages/index.vue]
<script setup lang="ts">
async function save() {
  await toast.loading($fetch("/api/save"), {
    loading: { title: "Saving" },
    success: { title: "Saved" },
    error: { title: "Failed" },
  });
}
</script>

<template>
  <UButton @click="save">Save</UButton>
</template>
```
::

## What The Module Gives You

::card-group
  :::card{icon="i-tabler-bell" title="Auto-imported toast"}
  Call 

  `toast.success(...)`

  , 

  `toast.loading(...)`

  , or 

  `toast.update(...)`

   without a manual import.
  :::

  :::card{icon="i-tabler-braces" title="Auto-imported useToast()"}
  Grab the same API once inside a component or composable and reuse it locally.
  :::

  :::card{icon="i-tabler-layout-navbar" title="Auto-registered ToastContainer"}
  Render 

  `<ToastContainer />`

   in 

  `app.vue`

   without importing it.
  :::

  :::card
  ---
  icon: i-tabler-package
  title: Vue runtime exports
  to: https://www.toastflow.top/docs/api/runtime-exports
  ---
  Use 

  `nuxt-toastflow/runtime`

   when you need explicit imports for 

  `Toast`

  , 

  `ToastProgress`

  , types, or lower-level runtime pieces.
  :::
::

## Read Next

::card-group
  :::card
  ---
  icon: i-tabler-braces
  title: toast vs useToast
  to: https://www.toastflow.top/docs/nuxt/toast-and-use-toast
  ---
  Pick the cleanest call style for pages, composables, and callbacks.
  :::

  :::card
  ---
  icon: i-tabler-adjustments-horizontal
  title: Module options
  to: https://www.toastflow.top/docs/nuxt/module-options
  ---
  Configure CSS injection, runtime config, and component registration.
  :::

  :::card
  ---
  icon: i-tabler-package
  title: Runtime exports
  to: https://www.toastflow.top/docs/api/runtime-exports
  ---
  See what is shared between Vue, Nuxt, and the headless core.
  :::

  :::card
  ---
  icon: i-tabler-player-play
  title: Live examples
  to: https://www.toastflow.top/docs/examples/live-examples
  ---
  Trigger real toasts from the docs.
  :::
::


# toast vs useToast()

Both are auto-imported by `nuxt-toastflow`. They point to the same Toastflow runtime.

::card-group
  :::card{icon="i-tabler-bolt" title="Use toast"}
  Best for one-off calls in pages, click handlers, composables, and callbacks.
  :::

  :::card{icon="i-tabler-braces" title="Use useToast()"}
  Best when you want to name the API once and pass it around explicitly.
  :::
::

## Side By Side

::code-group
```ts [toast.ts]
toast.success({
  title: "Saved",
});
```

```ts [use-toast.ts]
const toastApi = useToast();

toastApi.success({
  title: "Saved",
});
```
::

## Same Store

```ts [same-store.ts]
const toastApi = useToast();

toastApi.dismissAll();
toast.dismissAll();
```

Both calls operate on the same queue, timers, subscriptions, and visible toasts.

## Common Nuxt Patterns

::tabs
  :::tabs-item{label="Click handler"}
  ```vue [components/CopyLink.vue]
  <script setup lang="ts">
  function copyLink() {
    toast.success({ title: "Copied" });
  }
  </script>

  <template>
    <UButton @click="copyLink">Copy link</UButton>
  </template>
  ```
  :::

  :::tabs-item{label="Composable"}
  ```ts [composables/useSaveProfile.ts]
  export function useSaveProfile() {
    const toastApi = useToast();

    return async function saveProfile(payload: unknown) {
      await toastApi.loading(
        $fetch("/api/profile", { method: "POST", body: payload }),
        {
          loading: { title: "Saving profile" },
          success: { title: "Profile saved" },
          error: { title: "Save failed" },
        },
      );
    };
  }
  ```
  :::

  :::tabs-item{label="Update by id"}
  ```ts [update-by-id.ts]
  const id = toast.show({
    type: "loading",
    title: "Uploading",
    duration: 0,
  });

  toast.update(id, {
    type: "success",
    title: "Upload complete",
    duration: 3000,
  });
  ```
  :::
::

## Client-Side Rule

::warning{icon="i-tabler-server-off"}
Do not call 

`toast`

 or 

`useToast()`

 from Nitro routes, server handlers, route middleware that only runs on the server, or SSR-only code. Toasts are UI feedback, so trigger them from client execution.
::

## Quick Decision

::accordion
  :::accordion-item{label="I am inside a Vue component event handler"}
  Use 

  `toast`

  . It keeps the file short and easy to scan.
  :::

  :::accordion-item{label="I am writing a reusable composable"}
  Use 

  `useToast()`

   when a named local API makes the composable clearer.
  :::

  :::accordion-item{label="I need a lower-level import"}
  Use 

  `nuxt-toastflow/runtime`

   for explicit runtime imports. See 

  [Runtime exports](https://www.toastflow.top/docs/api/runtime-exports)

  .
  :::
::


# Nuxt Module Options

`nuxt-toastflow` adds Nuxt-specific wiring around the shared Toastflow config.

::field-group
  :::field{name="config" type="ToastConfig"}
  Shared Toastflow runtime config. Default: 

  `{}`

  .
  :::

  :::field{name="css" type="boolean"}
  Toggle shipped CSS injection. Default: 

  `true`

  .
  :::

  :::field{name="componentName" type="string | false"}
  Rename or disable the auto-registered container. Default: 

  `"ToastContainer"`

  .
  :::

  :::field{name="components" type="boolean"}
  Auto-register the remaining components (

  `Toast`

  , icons, …). Default: 

  `true`

  .
  :::
::

## Full Example

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["nuxt-toastflow"],
  toastflow: {
    css: true,
    componentName: "ToastContainer",
    config: {
      position: "top-right",
      alignment: "left",
      duration: 5000,
      maxVisible: 5,
      queue: true,
      pauseOnHover: true,
    },
  },
});
```

## Option Details

::accordion
  :::accordion-item{label="config"}
  Everything you would pass to `createToastflow(...)` in Vue goes under `toastflow.config`.

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    toastflow: {
      config: {
        position: "bottom-right",
        duration: 4000,
        maxVisible: 3,
        queue: true,
      },
    },
  });
  ```

  Keep this JSON-serializable. Runtime callbacks belong on individual toast calls.
  :::

  :::accordion-item{label="css"}
  Leave `css: true` for the normal path. Set it to `false` when you want to own stylesheet loading.

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    css: ["~/assets/toastflow.css"],
    toastflow: {
      css: false,
    },
  });
  ```
  :::

  :::accordion-item{label="componentName"}
  Rename the auto-registered component:

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    toastflow: {
      componentName: "AppToasts",
    },
  });
  ```

  Or disable registration and import explicitly:

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    toastflow: {
      componentName: false,
    },
  });
  ```

  The registered component supports the same `id` prop as in Vue, so you can mount several containers and route toasts with `containerId` — see [Multiple Containers](https://www.toastflow.top/docs/vue/multiple-containers).
  :::

  :::accordion-item{label="components"}
  By default the module also auto-registers `Toast`, `ToastProgress`, and the icon components (`ArrowPath`, `Bell`, `CheckCircle`, `InfoCircle`, `QuestionMarkCircle`, `XCircle`, `XMark`) under their export names — useful for headless slots and custom rendering.

  The icon names are generic; if one collides with your own components or an icon library, turn the registration off and import what you need from `nuxt-toastflow/runtime`:

  ```ts [nuxt.config.ts]
  export default defineNuxtConfig({
    modules: ["nuxt-toastflow"],
    toastflow: {
      components: false,
    },
  });
  ```

  ```vue [app/components/MyToast.vue]
  <script setup lang="ts">
  import { CheckCircle } from "nuxt-toastflow/runtime";
  </script>
  ```
  :::
::

## JSON-Serializable Config

::warning
Do not put functions in 

`toastflow.config`

. Nuxt config is serialized. Use per-toast callbacks like 

`onClose`

, 

`onClick`

, or button 

`onClick`

 at runtime.
::

::code-tree{expand-all default-value="runtime/toast.ts"}
```ts [runtime/toast.ts]
toast.success({
  title: "Saved",
  onClose() {
    console.log("toast closed");
  },
});
```

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  toastflow: {
    config: {
      onClose() {
        console.log("not serializable here");
      },
    },
  },
});
```
::

## Related

::card-group
  :::card
  ---
  icon: i-tabler-package
  title: Runtime exports
  to: https://www.toastflow.top/docs/api/runtime-exports
  ---
  Import 

  `ToastContainer`

  , 

  `Toast`

  , 

  `toast`

  , types, or lower-level runtime pieces explicitly.
  :::

  :::card
  ---
  icon: i-tabler-note
  title: Nuxt notes
  to: https://www.toastflow.top/docs/nuxt/nuxt-notes
  ---
  Client-only usage, SSR boundaries, and practical app patterns.
  :::
::


# Nuxt Notes

Toastflow is UI feedback. In Nuxt, that means the trigger should happen where the browser can show it.

## Safe Places To Call Toasts

::card-group
  :::card{icon="i-tabler-hand-click" title="Click handlers"}
  Show feedback after a user action.
  :::

  :::card{icon="i-tabler-device-desktop-check" title="onMounted"}
  Show a toast after client hydration if the page needs it.
  :::

  :::card{icon="i-tabler-braces" title="Client composables"}
  Wrap request flows and call 

  `toast.loading(...)`

   from client code.
  :::
::

## Avoid Server-Only Places

::warning{icon="i-tabler-server-off"}
Do not trigger toasts from Nitro routes, server handlers, server-only plugins, or code that runs only during SSR. Return data/errors from the server, then show UI feedback on the client.
::

## Functions Cannot Live In `nuxt.config`

The `toastflow.config` object in `nuxt.config` is JSON-serialized into the generated plugin. Functions (`sanitizer`, `createdAtFormatter`, `onMount`, `onClose`, button `onClick`, …), `Date`, and `RegExp` values do not survive that — the module warns with the exact config path and omits them.

Pass function options per toast instead; those run entirely at runtime and work as expected:

```ts [per-toast-functions.ts]
toast.show({
  type: "success",
  title: "Saved",
  showCreatedAt: true,
  createdAtFormatter: (createdAt) => new Date(createdAt).toLocaleTimeString(),
  onClose: () => console.log("closed"),
});
```

::note
Global function defaults are currently not supported through the Nuxt module config.
::

## Common Patterns

::code-group
```ts [request-flow.ts]
const toastApi = useToast();

const request = toastApi.loading($fetch("/api/save", { method: "POST" }), {
  loading: { title: "Saving" },
  success: { title: "Saved" },
  error: { title: "Failed" },
});

await request;
```

```ts [update-later.ts]
const id = toast.show({
  type: "loading",
  title: "Uploading",
  duration: 0,
});

toast.update(id, {
  type: "success",
  title: "Done",
  duration: 3000,
});
```
::

## Related Guides

::card-group
  :::card
  ---
  icon: i-tabler-palette
  title: Styling
  to: https://www.toastflow.top/docs/global/styling
  ---
  Use the shared Vue/Nuxt styling model without repeating it here.
  :::

  :::card
  ---
  icon: i-tabler-package
  title: Runtime exports
  to: https://www.toastflow.top/docs/api/runtime-exports
  ---
  Use explicit imports only when the Nuxt auto-imports are not enough.
  :::
::


# Headless Core Store

::docs-npm-badges{downloads packages="toastflow-core:64748b"}
::

Use `toastflow-core` when you want Toastflow behavior without the Vue UI.

::tip
If you are already in Vue or Nuxt and only want custom markup, use the 

[Headless Slot](https://www.toastflow.top/docs/headless/headless-slot)

 first. It is less work.
::

## Install

::code-group
```bash [pnpm]
pnpm add toastflow-core
```

```bash [npm]
npm install toastflow-core
```

```bash [yarn]
yarn add toastflow-core
```
::

## Create A Store

```ts [toast-store.ts]
import { createToastStore } from "toastflow-core";

export const store = createToastStore({
  position: "bottom-right",
  maxVisible: 3,
  queue: true,
});
```

## Render Your Own UI

::code-group
```ts [toast-store.ts]
import { createToastStore } from "toastflow-core";

export const store = createToastStore();
```

```ts [renderer.ts]
import { store } from "./toast-store";

store.subscribe((state) => {
  renderToasts(state.toasts);
  renderQueueCount(state.queue.length);
});
```

```ts [actions.ts]
import { store } from "./toast-store";

const id = store.show({
  type: "info",
  title: "Renderer connected",
});

store.update(id, {
  type: "success",
  title: "Updated",
});
```
::

## Teardown

If the store's lifetime is shorter than the page (tests, micro-frontends, embedded widgets), call `destroy()` when you are done. It cancels all pending timers, clears state and queue, and drops every listener:

```ts [teardown.ts]
store.destroy();
// The store must not be used after this point.
```

## What You Keep

::card-group
  :::card{icon="i-tabler-list-details" title="Queue behavior"}
  Keep overflow handling, max visible limits, and queue pause/resume.
  :::

  :::card{icon="i-tabler-stopwatch" title="Timers"}
  Keep duration, pause-on-hover-compatible timer state, and loading updates.
  :::

  :::card{icon="i-tabler-radio" title="Events"}
  Subscribe to state and Toastflow events for analytics or renderer updates.
  :::
::

## When To Use Core

::accordion
  :::accordion-item{label="Use core"}
  Use it for non-Vue apps, design-system renderers, or advanced UI shells where you want full DOM control.
  :::

  :::accordion-item{label="Do not use core yet"}
  If you are in Vue and only dislike the default card, use the headless slot. You keep accessibility helpers and avoid rebuilding renderer logic.
  :::
::


# Headless Slot

Use the `ToastContainer` slot in Vue or Nuxt when you like Toastflow's runtime behavior but need your own card markup.

Container-level features keep working with a custom slot: [multiple containers](https://www.toastflow.top/docs/vue/multiple-containers) (the `id` prop) and `overflowScroll`.

## Basic Slot

```vue [App.vue]
<template>
  <ToastContainer v-slot="{ toast, ui }">
    <div v-bind="ui.wrapperProps">
      <article v-bind="ui.getRootProps({ class: 'my-toast' })">
        <strong>{{ toast.title }}</strong>
        <p v-if="toast.description">{{ toast.description }}</p>

        <button v-bind="ui.getCloseProps()">Close</button>
      </article>
    </div>
  </ToastContainer>
</template>
```

## Actions And Progress

::code-group
```vue [actions.vue]
<template>
  <button
    v-for="button in ui.buttons.items"
    :key="button.id"
    v-bind="ui.getButtonProps(button)"
  >
    {{ button.label }}
  </button>
</template>
```

```vue [progress.vue]
<template>
  <div v-if="ui.progress.show" v-bind="ui.progress.getTrackProps()">
    <div v-bind="ui.progress.getBarProps()" />
  </div>
</template>
```

```vue [close.vue]
<template>
  <button v-bind="ui.getCloseProps({ class: 'close-button' })">Close</button>
</template>
```
::

## What `ui` Gives You

::card-group
  :::card{icon="i-tabler-shield-check" title="Accessibility props"}
  `wrapperProps`

   and 

  `getRootProps()`

   keep structure, roles, labels, and live-region behavior intact.
  :::

  :::card{icon="i-tabler-x" title="Dismiss behavior"}
  `getCloseProps()`

   wires the button to the correct toast id.
  :::

  :::card{icon="i-tabler-hand-click" title="Action buttons"}
  `getButtonProps(button)`

   preserves click handling, dismiss-on-click, and ARIA labels.
  :::

  :::card{icon="i-tabler-gauge" title="Progress helpers"}
  `progress.*`

   helpers let you keep Toastflow's timer state while drawing your own bar.
  :::
::

## Full Examples

The full headless playground below runs in the Vue REPL. It uses the same `headlessFiles` source as the Live Examples page, so the code and preview stay in one place.

::docs-headless-full-examples
## Slot Props Reference

The `ToastContainer` default slot provides these props:

  :::field-group
    ::::field{name="toast" type="ToastInstance"}
    Current toast data.
    ::::

    ::::field{name="ui" type="ToastUI"}
    Structured helpers (preferred API).
    ::::

    ::::field{name="progressResetKey" type="number"}
    Changes when timer/progress should restart.
    ::::

    ::::field{name="duplicateKey" type="number"}
    Changes on duplicate event.
    ::::

    ::::field{name="updateKey" type="number"}
    Changes on update event.
    ::::

    ::::field{name="bumpAnimationClass" type="string"}
    Duplicate bump animation class.
    ::::

    ::::field{name="clearAllAnimationClass" type="string"}
    Clear-all animation class.
    ::::

    ::::field{name="updateAnimationClass" type="string"}
    Update animation class.
    ::::

    ::::field{name="dismiss" type="(id) => void"}
    Dismiss helper.
    ::::
  :::

### `ui` Highlights

- **`wrapperProps`** / **`getRootProps()`** — Structure, roles, labels, live-region
- **`getCloseProps()`** — Close button wiring
- **`getButtonProps(button)`** — Action button click + ARIA
- **`progress.show`**, **`progress.trackProps`**, **`progress.barProps`** — Timer-aware progress helpers
- **`buttons.items`** — Resolved button array
- **`icon`**, **`createdAt`** — Derived rendering state

  :::note
  **Full slot payload types:**

   

  [`packages/vue/src/toast-ui.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/vue/src/toast-ui.ts){rel=""nofollow"" target="\_blank"}
  :::

## Slot vs Core

  :::accordion
    ::::accordion-item{label="Use the slot"}
    Use it when you are in Vue or Nuxt and only want to replace markup/styles.
    ::::

    ::::accordion-item{label="Use toastflow-core"}
    Use it when you are outside Vue or building an entirely custom renderer.
    ::::
  :::
::


# Live Examples

Use these examples to feel the runtime behavior before copying code into your app. They mirror the examples from the previous documentation.

::note
The examples run in the browser through the Vue REPL. They use the same Toastflow store, timers, queue logic, and action handling as a real app.
::

::docs-live-examples
## Copy the Same Patterns

  :::code-tree{expand-all default-value="success.ts"}
  ```ts [success.ts]
  toast.success({
    title: "Saved",
    description: "Your changes are live.",
  });
  ```

  ```ts [loading.ts]
  await toast.loading(fetch("/api/save"), {
    loading: { title: "Saving" },
    success: { title: "Saved" },
    error: { title: "Failed" },
  });
  ```

  ```ts [action.ts]
  toast.info({
    title: "File archived",
    buttons: {
      alignment: "bottom-right",
      buttons: [
        {
          label: "Undo",
          dismissAfterClick: true,
          onClick() {
            toast.success({ title: "Restored" });
          },
        },
      ],
    },
  });
  ```
  :::

## Where to Use Them

  :::card-group
    ::::card
    ---
    icon: i-simple-icons-vuedotjs
    title: Vue
    to: https://www.toastflow.top/docs/vue/quick-start
    ---
    Use the same 

    `toast.*`

     helpers after 

    `createToastflow()`

     is installed.
    ::::

    ::::card
    ---
    icon: i-simple-icons-nuxtdotjs
    title: Nuxt
    to: https://www.toastflow.top/docs/nuxt/toast-and-use-toast
    ---
    Use the auto-imported 

    `toast`

     or grab the same API with 

    `useToast()`

    .
    ::::

    ::::card
    ---
    icon: i-tabler-automation
    title: Headless
    to: https://www.toastflow.top/docs/headless/core-store
    ---
    Use 

    `toastflow-core`

     when you want the behavior without Toastflow's Vue UI.
    ::::
  :::
::


# Configuration

Toastflow resolves config in three layers:

::steps
### 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`.
::

::note
**Full TypeScript definitions:**

 

[`packages/core/src/types.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/types.ts){rel=""nofollow"" target="\_blank"}

. The reference below covers the most common options.
::

## Layout & Position

::field-group
  :::field{name="position" type="ToastPosition"}
  Viewport anchor for the stack. Default: 

  `"top-right"`

  .
  :::

  :::field
  ---
  name: alignment
  type: '"left" | "center" | "right"'
  ---
  Text direction inside the toast body. Default: 

  `"left"`

  .
  :::

  :::field{name="offset" type="string"}
  Distance from the viewport edge. Default: 

  `"16px"`

  .
  :::

  :::field{name="gap" type="string"}
  Gap between toasts. Default: 

  `"8px"`

  .
  :::

  :::field{name="width" type="string"}
  Default toast width. Default: 

  `"350px"`

  .
  :::

  :::field{name="zIndex" type="number"}
  Root container z-index. Default: 

  `9999`

  .
  :::

  :::field{name="overflowScroll" type="boolean"}
  Scroll the stack when it grows taller than the viewport. Default: 

  `false`

  .
  :::

  :::field{name="containerId" type="string"}
  Target a specific 

  `<ToastContainer id>`

   (

  [details](https://www.toastflow.top/docs/vue/multiple-containers)

  ). No default.
  :::
::

## Timing & Progress

::field-group
  :::field{name="duration" type="number"}
  Auto-dismiss delay in ms. Default: 

  `5000`

  . 

  `Infinity`

   / 

  `0`

   \= no auto-dismiss.
  :::

  :::field{name="pauseOnHover" type="boolean"}
  Pause the timer on hover or touch. Default: 

  `true`

  .
  :::

  :::field{name="pauseStrategy" type=""resume" | "reset""}
  `"resume"`

   continues the remaining time, 

  `"reset"`

   restarts the full duration. Default: 

  `"resume"`

  .
  :::

  :::field{name="progressBar" type="boolean"}
  Show a progress bar for finite durations. Default: 

  `true`

  .
  :::

  :::field
  ---
  name: progressAlignment
  type: '"right-to-left" | "left-to-right"'
  ---
  Progress animation direction. Default: 

  `"right-to-left"`

  .
  :::

  :::field{name="showCreatedAt" type="boolean"}
  Show a timestamp badge on the toast. Default: 

  `false`

  .
  :::

  :::field{name="createdAtFormatter" type="(createdAt: number) => string"}
  Function formatting the timestamp (

  [see below](https://www.toastflow.top/#timestamps)

  ). Default: locale time.
  :::
::

## Stacking & Queue

::field-group
  :::field{name="maxVisible" type="number"}
  Max visible toasts per position. Default: 

  `5`

  . 

  `<= 0`

   \= no cap.
  :::

  :::field{name="queue" type="boolean"}
  Queue overflowed toasts instead of evicting. Default: 

  `false`

  .
  :::

  :::field{name="order" type=""newest" | "oldest""}
  Insert order and eviction target. Default: 

  `"newest"`

  .
  :::

  :::field{name="preventDuplicates" type="boolean"}
  De-duplicate by container + position + type + title + description. Default: 

  `false`

  .
  :::
::

## Interaction

::field-group
  :::field{name="closeButton" type="boolean"}
  Show the floating close button. Default: 

  `true`

  .
  :::

  :::field{name="closeOnClick" type="boolean"}
  Dismiss on body click. Default: 

  `false`

  .
  :::

  :::field{name="swipeToDismiss" type="boolean"}
  Dismiss with a right swipe/drag. Default: 

  `false`

  .
  :::
::

## Content & Appearance

::field-group
  :::field{name="showIcon" type="boolean"}
  Show the type icon. Default: 

  `true`

  .
  :::

  :::field{name="supportHtml" type="boolean"}
  Allow HTML in title and description — use trusted content only. Default: 

  `false`

  .
  :::

  :::field{name="sanitizer" type="(html: string) => string"}
  Hook sanitizing HTML before render, e.g. DOMPurify (

  [details](https://www.toastflow.top/docs/global/styling#sanitizer-hook)

  ). No default.
  :::

  :::field{name="css" type="ToastCSSOverrides"}
  CSS variable overrides (

  `bg`

  , 

  `color`

  , 

  `accentColor`

  , …). Works globally and per-toast — per-toast values merge over the global ones (

  [details](https://www.toastflow.top/docs/global/styling)

  ). No default.
  :::
::

## Per-Toast Only Options

Available on `show`, typed helpers, and `update` — not in global config:

::field-group
  :::field{name="theme" type="string"}
  CSS accent class, e.g. 

  `"brand"`

   → 

  `tf-toast-accent--brand`

   (

  [details](https://www.toastflow.top/docs/global/styling#the-three-levels)

  ).
  :::
::

## Example

::code-group
```ts [global-config.ts]
import { createToastflow } from "vue-toastflow";

app.use(
  createToastflow({
    position: "top-right",
    duration: 5000,
    maxVisible: 4,
    queue: true,
    pauseStrategy: "resume",
    preventDuplicates: true,
  }),
);
```

```ts [per-toast-override.ts]
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:

```ts [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:

```ts [created-at-formatter.ts]
createToastflow({
  showCreatedAt: true,
  createdAtFormatter: (createdAt) =>
    new Date(createdAt).toLocaleTimeString([], {
      hour: "2-digit",
      minute: "2-digit",
    }),
});
```

::warning
`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](https://www.toastflow.top/docs/nuxt/nuxt-notes)

.
::

## Buttons Config

```ts [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)`.

::caution
`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.
::

::note
**Full button types:**

 see 

[`ToastButtonsConfig`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/types.ts){rel=""nofollow"" target="\_blank"}

 for the complete shape.
::


# Actions

Actions are the mutating methods on `toast` (Vue/Nuxt) or `store` (headless).

::note
**Full method signatures:**

 

[`packages/core/src/store.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/store.ts){rel=""nofollow"" target="\_blank"}

.
::

## Method Overview

::field-group
  :::field{name="show" type="(options | title, options?) => ToastId"}
  Create a toast, returns 

  `ToastId`

  .
  :::

  :::field{name="loading" type="(input, config) => Promise"}
  Bind an async flow to loading → success / error (

  [see below](https://www.toastflow.top/#loading-helper)

  ).
  :::

  :::field{name="update" type="(id, options) => void"}
  Patch an existing toast in place.
  :::

  :::field{name="dismiss" type="(id) => void"}
  Dismiss one toast.
  :::

  :::field{name="dismissAll" type="(filter?: { containerId?: string }) => void"}
  Dismiss all visible and queued toasts, optionally scoped to a container.
  :::

  :::field{name="pause" type="(id) => void"}
  Pause the timer for one toast.
  :::

  :::field{name="resume" type="(id) => void"}
  Resume the timer using 

  `pauseStrategy`

  .
  :::

  :::field{name="pauseQueue" type="() => void"}
  Pause queue processing globally.
  :::

  :::field{name="resumeQueue" type="() => void"}
  Resume queue processing.
  :::

  :::field{name="getState" type="() => ToastState"}
  Current state snapshot.
  :::

  :::field{name="getConfig" type="() => ToastConfig"}
  Resolved global config.
  :::

  :::field{name="subscribe" type="(listener) => () => void"}
  Continuous state updates, returns an unsubscribe function.
  :::

  :::field{name="subscribeEvents" type="(listener) => () => void"}
  One-off event stream (

  [details](https://www.toastflow.top/docs/api/events)

  ).
  :::
::

Typed wrappers: `default`, `success`, `error`, `info`, `warning`, `custom` — they pin the `type` field automatically.

## Create Call Styles

| Style                      | Use when                                     |
| -------------------------- | -------------------------------------------- |
| `toast.show({ ... })`      | You already have a full payload object       |
| `toast.show(title, opts)`  | The title is the primary thing being shown   |
| `toast.success({ ... })`   | The toast type is known at the call site     |
| `toast.error(title, opts)` | You want a typed helper with title + options |

See [Toasts](https://www.toastflow.top/docs/vue/toasts#create-toasts) for runnable examples.

::warning
`title`

 or 

`description`

 must be non-empty. Empty content throws.
::

## Loading Helper

```ts [loading.ts]
await toast.loading(new Promise((resolve) => window.setTimeout(resolve, 900)), {
  loading: { title: "Saving" },
  success: { title: "Saved" },
  error: { title: "Failed" },
});
```

The loading toast uses `duration: Infinity` and `progressBar: false`. On resolve/reject, the same toast id transitions to success or error.

For real requests, pass `fetch`, `$fetch`, or a function that returns a promise. `success` and `error` can also be functions when the final message needs response data.

::warning
`loading(...)`

 returns the wrapped promise — it 

**rejects**

 when the task fails (the error toast is shown either way). If you fire-and-forget the call, attach a 

`.catch(() => {})`

 or the rejection surfaces as an unhandled promise rejection.
::

::docs-toast-preview{variant="loading"}
## Update

```ts [update.ts]
const id = toast.show({
  type: "loading",
  title: "Uploading",
  description: "Waiting for the update call...",
  duration: 0,
  progressBar: false,
});

window.setTimeout(() => {
  toast.update(id, {
    type: "success",
    title: "Upload complete",
    description: "The same toast id was patched in place.",
    duration: 3500,
    progressBar: true,
  });
}, 900);
```

  :::docs-toast-preview{variant="update"}
  - Visible toast timer is re-scheduled on update.
  - Queued toast instance is replaced in queue.

  ## Dismiss

    ::::code-tree{expand-all default-value="dismiss-one.ts"}
    ```ts [dismiss-one.ts]
    toast.dismiss(id);
    ```

    ```ts [dismiss-all.ts]
    toast.dismissAll();
    ```

    ```ts [dismiss-container.ts]
    toast.dismissAll({ containerId: "panel" }); // only container "panel"
    ```
    ::::

  `dismiss` fires `onClose`, marks the toast as `leaving`, then removes it after the leave delay. `dismissAll` marks visible toasts as `clear-all`. Scoping `dismissAll` to a container is covered in [Multiple containers](https://www.toastflow.top/docs/vue/multiple-containers).

  ## Queue Controls

  ```ts [queue-controls.ts]
  toast.pauseQueue();
  toast.resumeQueue();
  ```

  Affects all positions. Only controls queue processing — existing visible toasts are not affected.
  :::
::


# Events

Toastflow emits lightweight events through `subscribeEvents`.

::note
Event types are defined in 

[`packages/core/src/types.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/types.ts){rel=""nofollow"" target="\_blank"}

 — look for 

`ToastEvent`

 and 

`ToastEventKind`

.
::

## Subscribe

::code-group
```ts [subscribe.ts]
const off = toast.subscribeEvents((event) => {
  console.log(event.kind, event.id);
});
```

```ts [unsubscribe.ts]
// call the returned function to stop listening
off();
```
::

## Event Kinds

::field-group
  :::field{name="duplicate" type="ToastEventKind"}
  `show(...)`

   found an existing match while 

  `preventDuplicates: true`

  .
  :::

  :::field{name="timer-reset" type="ToastEventKind"}
  A visible toast timer was reset (update, or resume with 

  `pauseStrategy: "reset"`

  ).
  :::

  :::field{name="update" type="ToastEventKind"}
  `update(id, options)`

   succeeded.
  :::
::

Each event is a `{ id, kind }` object — `id` is the affected toast's `ToastId`.

## Behavior Notes

::accordion
  :::accordion-item{label="duplicate + update overlap"}
  Both events can fire in the same duplicate handling flow, depending on the action path.
  :::

  :::accordion-item{label="Queued toast updates"}
  Updating a queued toast emits 

  `update`

   but not 

  `timer-reset`

   — no active timer exists yet.
  :::

  :::accordion-item{label="Separate from state stream"}
  The event stream does not carry state snapshots. Use 

  `subscribe(listener)`

   for state.
  :::
::

## Typical Uses

- Trigger CSS bump or progress reset animations
- Analytics and telemetry for notification flows
- Debug queue and timer behavior during development


# State

Toastflow state is intentionally small — visible toasts and queued toasts.

::note
**Full type definitions:**

 

[`packages/core/src/types.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/types.ts){rel=""nofollow"" target="\_blank"}

 — look for 

`ToastState`

, 

`ToastInstance`

, and 

`ToastContext`

.
::

## Shape

::field-group
  :::field{name="toasts" type="ToastInstance[]"}
  Currently visible toasts, including transitional phases.
  :::

  :::field{name="queue" type="ToastInstance[]"}
  Queued toasts waiting for capacity.
  :::
::

## Lifecycle Phases

Each visible toast carries an optional `phase`:

| Phase       | Meaning                                |
| ----------- | -------------------------------------- |
| `enter`     | Just inserted, enter animation playing |
| `leaving`   | Dismiss animation for a single toast   |
| `clear-all` | Batch dismiss animation                |

## State Flow

::steps
### `show(...)`

Toast enters state with `phase: "enter"`.

### `dismiss(id)`

Toast becomes `phase: "leaving"`.

### After leave timeout

Toast removed from `state.toasts`. Queue processes next if capacity opens.
::

## Subscribe

```ts [subscribe-state.ts]
const stop = toast.subscribe((state) => {
  console.log("visible:", state.toasts.length);
  console.log("queued:", state.queue.length);
});

stop();
```

The listener fires immediately with the current snapshot on subscribe.

## Getters

::code-group
```ts [state-snapshot.ts]
const state = toast.getState();
console.log(state.toasts, state.queue);
```

```ts [resolved-config.ts]
const config = toast.getConfig();
console.log(config.position, config.duration);
```
::

Use `getState()` for on-demand checks. For continuous reactivity, prefer `subscribe(...)`.


# Runtime Exports

Toastflow exposes the same runtime model through each package. Use the import path that matches your app, then keep the same API names across Vue, Nuxt, and headless usage.

::note
**Full TypeScript definitions:**

 

[`packages/core/src/types.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/core/src/types.ts){rel=""nofollow"" target="\_blank"}

 and 

[`packages/vue/src/index.ts`](https://github.com/adrianjanocko/toastflow/blob/main/packages/vue/src/index.ts){rel=""nofollow"" target="\_blank"}

.
::

## Import Paths

| App type           | Import from              | Use for                                     |
| ------------------ | ------------------------ | ------------------------------------------- |
| Vue app            | `vue-toastflow`          | Plugin, components, `toast`, types, helpers |
| Nuxt auto-imports  | `nuxt-toastflow` module  | `toast`, `useToast()`, `<ToastContainer />` |
| Nuxt explicit path | `nuxt-toastflow/runtime` | Manual component/API imports                |
| Headless runtime   | `toastflow-core`         | Store, state, events, types, and utilities  |

## Package Map

::code-tree{expand-all default-value="vue/runtime.ts"}
```ts [vue/runtime.ts]
import {
  createToastflow,
  toast,
  ToastContainer,
  Toast,
  ToastProgress,
  type ToastConfig,
  type ToastState,
} from "vue-toastflow";
```

```ts [nuxt/auto-imports.ts]
// Auto-imported after modules: ["nuxt-toastflow"]
toast.success({ title: "Saved" });

const toastApi = useToast();
toastApi.dismissAll();
```

```ts [nuxt/runtime.ts]
import {
  toast,
  ToastContainer,
  Toast,
  ToastProgress,
  type ToastConfig,
  type ToastState,
} from "nuxt-toastflow/runtime";
```

```ts [headless/core.ts]
import {
  createToastStore,
  type ToastConfig,
  type ToastState,
  type ToastInstance,
} from "toastflow-core";
```
::

## Export Groups

::card-group
  :::card{icon="i-tabler-layout-board-split" title="Components"}
  `ToastContainer`

  , 

  `Toast`

  , 

  `ToastProgress`

  , and the built-in icon components.
  :::

  :::card{icon="i-tabler-bell" title="Runtime API"}
  `toast`

  , 

  `createToastflow`

  , typed helpers, loading flow, update, dismiss, queue controls, state getters, and subscriptions.
  :::

  :::card{icon="i-tabler-file-code-2" title="Types"}
  `ToastConfig`

  , 

  `ToastInstance`

  , 

  `ToastState`

  , 

  `ToastContext`

  , action button types, event types, and payload/update inputs.
  :::

  :::card{icon="i-tabler-automation" title="Headless Core"}
  `createToastStore`

  , state subscriptions, event subscriptions, validators, UUID utility, and default formatter utilities.
  :::
::

## Icon Components

The built-in SVG icons are exported for custom renderers: `CheckCircle` (success), `XCircle` (error), `InfoCircle` (info), `QuestionMarkCircle` (warning), `ArrowPath` (loading), `Bell` (default), and `XMark` (close). Use them when building your own card with the [headless slot](https://www.toastflow.top/docs/headless/headless-slot):

```vue [App.vue]
<script setup lang="ts">
import { ToastContainer, CheckCircle } from "vue-toastflow";
</script>

<template>
  <ToastContainer v-slot="{ toast }">
    <div class="my-toast">
      <CheckCircle v-if="toast.type === 'success'" class="my-icon" />
      <p>{{ toast.title }}</p>
    </div>
  </ToastContainer>
</template>
```

## Nuxt Runtime Path

Use `nuxt-toastflow/runtime` only when auto-imports are not enough:

::code-group
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ["nuxt-toastflow"],
  toastflow: {
    componentName: false,
  },
});
```

```vue [app.vue]
<script setup lang="ts">
import { ToastContainer } from "nuxt-toastflow/runtime";
</script>

<template>
  <ToastContainer />
  <NuxtPage />
</template>
```
::

For normal Nuxt pages, prefer the module auto-imports documented in [toast vs useToast](https://www.toastflow.top/docs/nuxt/toast-and-use-toast).


# Troubleshooting

Quick solutions for the most common problems.

::accordion
  :::accordion-item{label="No toast appears"}
  Check all four points first:

  1. `createToastflow(...)` is called during app setup (Vue) or `nuxt-toastflow` is in `modules` (Nuxt).
  2. `<ToastContainer />` is rendered in the active component tree.
  3. You call `toast.*` after the store is initialized.
  4. If the toast sets a `containerId`, a matching `<ToastContainer id>` must be mounted — a mismatch logs a one-shot `[vue-toastflow]` console warning (see [Multiple Containers](https://www.toastflow.top/docs/vue/multiple-containers)).
  :::

  :::accordion-item{label="Error: store not initialized"}
  ```txt
  [vue-toastflow] Toast store not initialized. Did you install the plugin?
  ```

  The `toast` helper was called before the store was created. Make sure `app.use(createToastflow(...))` runs early in your setup.
  :::

  :::accordion-item{label="Progress bar is missing"}
  Possible reasons:

  - `progressBar` is `false`
  - `duration` is `Infinity` or `0`
  - A custom slot replaced the progress renderer
  :::

  :::accordion-item{label="Toast dismisses too fast or resets unexpectedly"}
  Check these options:

  - `duration` - is it shorter than expected?
  - `pauseOnHover` - is it disabled?
  - `pauseStrategy` - `"reset"` restarts the full duration on resume
  - `update(...)` calls reset the timer on visible toasts
  - `preventDuplicates: true` merges and restarts matching toasts
  :::

  :::accordion-item{label="Duplicate toasts still appear"}
  `preventDuplicates`

   compares only 

  `position`

  , 

  `containerId`

  , 

  `type`

  , 

  `title`

  , and 

  `description`

  . If any of these differ, the toast is not treated as a duplicate.
  :::

  :::accordion-item{label="Queue looks stuck"}
  Likely causes:

  - Queue is paused - call `toast.resumeQueue()`
  - No capacity - `maxVisible` is still full
  - You are checking a different position stack

  Inspect with `toast.getState()`.
  :::

  :::accordion-item{label="update() throws validation error"}
  `update(id, options)`

   requires at least one non-empty text field (

  `title`

   or 

  `description`

  ).
  :::

  :::accordion-item{label="HTML content renders as plain text"}
  Set 

  `supportHtml: true`

   on the toast. HTML is rendered as-is unless you configure the 

  [`sanitizer` hook](https://www.toastflow.top/docs/global/styling#sanitizer-hook)

   — use trusted content only.
  :::

  :::accordion-item{label="Types or autocomplete missing (Nuxt)"}
  Nuxt generates the Toastflow types (auto-imported `toast` / `useToast`, `$toast`, the `<ToastContainer>` component including its slot props, and the `toastflow` key in `nuxt.config`) into `.nuxt/` — they exist only after Nuxt has run at least once:

  1. Run `npx nuxi prepare` (or just start `nuxi dev` once).
  2. Make sure your `tsconfig.json` extends `./.nuxt/tsconfig.json` (default in scaffolded projects).
  3. Restart the editor's TS server if completions still don't show up.

  The `toastflow` key in `nuxt.config` is fully typed — every `ToastConfig` option autocompletes. If it doesn't, check that `nuxt-toastflow` is installed as a dependency (not just referenced in `modules`) and re-run `nuxi prepare`.
  :::

  :::accordion-item{label="Animations feel off"}
  Check:

  - CSS class overrides in the `animation` config
  - CSS variables `--tf-toast-animation-in-duration` and `--tf-toast-animation-out-duration`
  - User preference for `prefers-reduced-motion`
  :::
::

## Diagnostic Tools

```ts [diagnostics.ts]
toast.getState();
toast.getConfig();
toast.subscribeEvents((event) => {
  console.log(event.kind, event.id);
});
```


# Comparisons

Toastflow is built for teams that want toast notifications to behave like a small runtime, not just a visual helper.

## Decision Matrix

::card-group
  :::card{icon="i-tabler-automation" title="Pick Toastflow"}
  You need queue control, typed state, lifecycle events, CSS-first styling, Nuxt integration, and a truly headless core.
  :::

  :::card{icon="i-tabler-bolt" title="Pick an opinionated toaster"}
  You want a narrow API, fixed visual direction, and very few configuration decisions.
  :::

  :::card{icon="i-tabler-plug" title="Pick a legacy plugin"}
  You only need a quick notification layer and do not need runtime state, headless rendering, or detailed queue behavior.
  :::
::

## Feature Lens

| Need                 | Toastflow answer                                                        | Why it matters                                                        |
| -------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------- |
| Runtime control      | `getState`, `subscribe`, `subscribeEvents`, `pauseQueue`, `resumeQueue` | Toasts can participate in workflow state, not only appear visually.   |
| Real headless mode   | `toastflow-core` exports the store, state, events, types, and helpers   | You can build any renderer in Vue, Nuxt, or outside Vue entirely.     |
| Vue custom rendering | `<ToastContainer v-slot>` exposes resolved UI props and helpers         | You can replace the toast card while keeping accessibility wiring.    |
| Nuxt integration     | `nuxt-toastflow` module with auto-imports and runtime exports           | Nuxt apps get setup, CSS injection, SSR-safe wiring, and components.  |
| Styling ownership    | CSS variables, theme classes, inline `css`, optional shipped CSS        | Design systems can own the final look without wrapping every toast.   |
| Async workflows      | `toast.loading(...)` transitions one toast id through states            | Loading, success, and error stay connected instead of spawning noise. |
| TypeScript surface   | Core types are exported through `toastflow-core`, Vue, and Nuxt runtime | App code can type payloads, state, events, buttons, and callbacks.    |

## Library Fit

::note
This is a good-faith summary of each library's focus, not a feature-by-feature benchmark. Libraries evolve — always check their current docs.
::

| Library                    | Best fit                                | Trade-off compared with Toastflow                                                                  |
| -------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Toastflow**              | Runtime-driven Vue/Nuxt apps            | More capability to learn because queue, state, styling, and headless are exposed.                  |
| **vue-sonner**             | Sonner-style product UI                 | Great for a constrained visual model; less focused on standalone runtime ownership.                |
| **notivue**                | Composable-first notification workflows | Strong Vue ergonomics; Toastflow puts more emphasis on exported core state and headless rendering. |
| **vue3-toastify**          | Toastify-style familiarity              | Familiar API shape; Toastflow is stronger when you need queue/state/headless control.              |
| **vue-toast-notification** | Fast plugin setup                       | Lightweight integration; fewer reasons to choose it when deep customization is required.           |
| **vue3-notification**      | Basic notification ergonomics           | Useful for simple notifications; not aimed at full toast runtime ownership.                        |

## Headless Difference

Toastflow has two customization levels:

::card-group
  :::card
  ---
  icon: i-tabler-template
  title: Headless slot
  to: https://www.toastflow.top/docs/headless/headless-slot
  ---
  Stay in Vue/Nuxt, render your own markup, and keep Toastflow's resolved props, ARIA labels, buttons, icons, progress helpers, and dismiss wiring.
  :::

  :::card
  ---
  icon: i-tabler-automation
  title: Core store
  to: https://www.toastflow.top/docs/headless/core-store
  ---
  Use 

  `toastflow-core`

   directly. You own every pixel and Toastflow only provides state, queueing, timers, updates, events, and types.
  :::
::

That second option is the important distinction: the headless package is not just "custom content". It is the runtime without the renderer.

## Summary

Choose **Toastflow** when notification behavior is part of your application architecture: queueing, async state, event subscriptions, TypeScript types, and renderer ownership matter. Choose a smaller opinionated toaster when your app only needs quick visual messages.


# Toastflow