Vue Toast Tailwind 🍞

A lightweight, modern, and highly customizable Vue 3 toast plugin powered by Tailwind CSS v4 and TypeScript.

✨ Live Interactive Demo / Playground ✨

📖 GitHub Repository

Features

• ⚡️ Built for Vue 3 Composition API
• 🎨 Styled exclusively with Tailwind CSS v4 (CSS-first)
• 📝 Fully typed with TypeScript
• 🧩 Universal support for ES Modules & CommonJS (umd)
• 🪶 Unopinionated and easily customizable
• 🎬 Smooth transition animations using native Vue <TransitionGroup>
• ⏳ Smart pause and resume interactions on hover

Installation

npm install vue-toast-tailwind

Note: Since this plugin relies on Tailwind CSS 4 components, make sure your primary application is capable of compiling or loading vanilla CSS or Tailwind setups correctly.

Setup

In your main.ts or main.js:

import { createApp } from 'vue';
import App from './App.vue';
import { ToastPlugin } from 'vue-toast-tailwind';

// Import the required CSS
import 'vue-toast-tailwind/style.css';

const app = createApp(App);

app.use(ToastPlugin, {
  position: 'top-right', // default global position
  duration: 4000, // available now as a global ToastOption fallback
  class: 'rounded-2xl shadow-lg border-2 border-transparent', // applies to ALL toasts by default
  toastDefaults: {
    // You can set specific options for specific toast types here!
    error: {
      title: 'Error',
      class:
        'border-l-4 border-l-red-500 rounded-none shadow-2xl bg-white text-black',
    },
    success: {
      duration: 5000,
    },
  },
});

app.mount('#app');

Usage

You can use the useToast composable from any component's <script setup> block:

<script setup lang="ts">
import { useToast } from 'vue-toast-tailwind';

const toast = useToast();

const showSuccess = () => {
  toast.success('Your changes have been saved!', {
    title: 'Success',
    duration: 3000, // optional, default 3000ms
  });
};

const showError = () => {
  toast.error('Failed to load data.', {
    title: 'Network Error',
  });
};

const showInfo = () => {
  toast.info('A new update is available.');
};

const showWarning = () => {
  toast.warning('Your session is about to expire.', { duration: 0 }); // 0 means persistent
};

// Or use the generic method
const showCustom = () => {
  const id = toast({
    type: 'default',
    message: 'Hello World',
    duration: 5000,
    dismissible: true,
  });

  // You can also manually close toasts
  // toast.remove(id)
};
</script>

<template>
  <button @click="showSuccess">Show Progress</button>
</template>

Plugin Global Options

When registering the plugin with app.use(ToastPlugin, options), you can configure default behaviors:

| Option | Type | Default | Description | | -------------------------- | --------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- | | position | ToastPosition | 'top-right' | Supported: top-right, top-left, bottom-right, bottom-left, top-center, bottom-center. | | maxToasts | number | undefined | Global maximum number of toasts visible at once. Oldest toast is removed if exceeded. | | toastDefaults | Record<ToastType, ToastOptions> | undefined | Set specific default options (like class, title, duration) bound to specific types. | | ...any ToastOption field | any | undefined | Any valid ToastOptions property (e.g. duration, class, dismissible, component) can be defined globally. |

Toast Options API

| Property | Type | Default | Description | | ---------------- | ---------------------------------------------------------- | ------------------ | ---------------------------------------------------------------- | | id | string | (auto generated) | Unique identifier for the toast. Useful for manual manipulation. | | message | string | (required) | Main body text of the toast. | | title | string | undefined | Bolded title text. | | type | 'success' \| 'error' \| 'info' \| 'warning' \| 'default' | 'default' | Contextual intent. Uses specific Tailwind colors. | | duration | number | 3000 | Auto-close timer in ms. 0 will make it persist. | | dismissible | boolean | true | Shows an X to allow manually dismissing. | | component | Component | undefined | Custom Vue component to render instead of the default layout. | | componentProps | Record<string, any> | undefined | Props to pass to the custom component. | | class | string | undefined | Additional custom Tailwind CSS classes to append. | | onOpen | () => void | undefined | Callback fired when the toast is rendered. | | onClose | () => void | undefined | Callback fired when the toast is removed. |

Dynamic Custom Components

You can completely replace the default toast UI with your own Vue component. It will automatically receive the toast object as a prop.

For full TypeScript support, you can pass your component's props interface <TProps> to the toast function to get strict type checking and auto-completion for componentProps:

import CustomToast from './CustomToast.vue';

// Define the props your custom component expects
interface MyToastProps {
  customIcon: string;
  userName?: string;
  onAction?: () => void;
}

// Pass the generic type to the toast function
toast.success<MyToastProps>('File uploaded!', {
  component: CustomToast,
  componentProps: {
    customIcon: 'document',
    onAction: () => console.log('Action clicked!'),
  },
});

Deep Merging componentProps

The plugin intelligently deep merges componentProps across three levels of specificity. This prevents total overrides of your custom component props and allows defining common props globally, and specific ones per instance:

app.use(ToastPlugin, {
  // Level 1: Global. Applied to ALL Custom Toasts
  componentProps: {
    avatarUrl: 'https://...',
    actionText: 'View',
  },
  toastDefaults: {
    // Level 2: Type-specific. Merged with Global.
    success: {
      componentProps: { actionText: 'Accept' },
    },
  },
});

// Level 3: Instance. Merged with Global + Type-specific.
toast.success<MyToastProps>('New user alert', {
  component: CustomToast,
  componentProps: {
    userName: 'Emilia Clarke', // only defined at instance level
    // `avatarUrl` is inherited from Global
    // `actionText` is inherited from Type-specific ('Accept')
  },
});

Dark Mode Support 🌙

This plugin uses the dark: variant out of the box so that your toasts seamlessly switch to a dark theme depending on your host application's setup. In Tailwind CSS v4, this plugin is explicitly built using the custom semantic class variant:

@custom-variant dark (&:where(.dark, .dark *));

This means your toasts will automatically turn dark if the <html> or <body> tag has the .dark class applied by your app.

TypeScript Support

The package is fully typed. You can import interfaces directly:

import type {
  ToastOptions,
  PluginOptions,
  ToastType,
  ToastPosition,
} from 'vue-toast-tailwind';

License

MIT