ToastContainer

The Vue component that renders toasts. Place it once in App.vue (or in your Nuxt layout). Uses <Teleport to="body"> internally.

<ToastContainer
  position="bottom-right"
  :max-visible="5"
  :gap="8"
  :offset-x="16"
  :offset-y="16"
  :z-index="9999"
  theme="system"
/>

Props

position

ToastPosition · default: 'bottom-right'

Default container position (per-toast position option overrides this). Falls back to the plugin/module's position option (GlobalToastOptions) when neither this prop nor a per-toast option is set.

maxVisible

number · default: 5

Maximum number of toasts shown at once; extras wait in a pending queue. Falls back to the plugin/module's maxVisible option when not set.

gap

number · default: 8

Vertical gap between toasts in pixels.

offsetX

number · default: 16

Horizontal distance from the screen edge in pixels.

offsetY

number · default: 16

Vertical distance from the screen edge in pixels.

zIndex

number · default: 9999

CSS z-index of the container.

expand

boolean · default: false

stackMode only: keep the stack permanently expanded, as if the container were always hovered. No effect unless stackMode is also set.

teleportTo

string · default: 'body'

CSS selector passed to <Teleport>.

context

ToastContext · default: global

Pass an isolated context from createToastContext().

theme

'light' | 'dark' | 'system' | ToastDesignTokens · default: —

Theme name or inline token overrides. Falls back to the plugin/module's theme option when not set.

stackMode

boolean · default: false

Sonner-style stack: inactive toasts collapse behind the front one; hover expands.

position, theme, and maxVisible read the plugin/module's GlobalToastOptions (via inject) whenever the matching prop isn't passed explicitly — so <ToastContainer /> with no props at all honors app.use(VueToastPlugin, { position: 'top-left', ... }) or a Nuxt app's vueToastKit: { ... } config.

Multiple containers

A single <ToastContainer> handles all positions automatically — each toast is rendered at its own position option, falling back to the container's position prop:

toast.success('Saved', { position: 'top-right' })
toast.error('Failed', { position: 'bottom-center' })
// Both appear in their respective corners from one <ToastContainer>

For fully isolated queues (separate notification zones), use createToastContext() with a dedicated container:

<template>
  <!-- Default global queue — bottom right -->
  <ToastContainer position="bottom-right" />

  <!-- Critical alerts — top center, separate queue -->
  <ToastContainer position="top-center" :context="alertCtx" :z-index="10000" />
</template>

<script setup lang="ts">
import { createToastContext, useToast } from 'vue-toast-kit'
const alertCtx = createToastContext()
const alertToast = useToast(alertCtx)
</script>

Slots

Override any part of the toast without losing the queue logic:

<ToastContainer>
  <!-- Replace the entire toast -->
  <template #toast="{ toast, dismiss }">
    <MyCustomToast :data="toast" @close="dismiss(toast.id)" />
  </template>
</ToastContainer>

toast

Scope: { toast, dismiss }

Full replacement of one toast (skips all sub-slots).

toast-icon

Scope: { toast }

Replace the icon only; falls back to ToastIcon.

toast-content

Scope: { toast }

Replace the entire message + actions area.

toast-action

Scope: { toast }

Replace the action / undo buttons; falls back to ToastActions.

toast-close

Scope: { toast, dismiss }

Replace the close button.

toast-undo

Scope: { toast, remaining }

Replace the progress bar at the bottom of the toast.

Grouping

Toasts with the same groupKey are collapsed into a single toast with a +N counter. Clicking the counter toggles the expanded state.

// All three calls produce one visible toast with "+2"
toast.info('New message from Alice', { groupKey: 'messages' })
toast.info('New message from Bob', { groupKey: 'messages' })
toast.info('New message from Carol', { groupKey: 'messages' })

The leader toast (first in the group) stays visible; subsequent toasts are hidden but tracked. When the leader is dismissed, the next toast becomes the leader automatically.

Grouping options

Option	Behaviour
groupKey: 'my-key'	Enable grouping for this toast
No groupKey	Toast is always shown individually

Stack mode (Sonner-style)

Enable stackMode on <ToastContainer> to collapse multiple toasts into a visual stack. The front toast is fully visible; behind it you see up to 2 ghost cards, slightly scaled and offset. Hovering the container expands them back to the normal stacked list.

<ToastContainer :stack-mode="true" position="bottom-right" />

Hover to expand, mouse-leave to collapse back.