Vue Toast

A lightweight, customizable toast notification library for Vue 3.

Features

• 🎨 Multiple toast types: Success, Error, Warning, Info, and Default
• 📍 Flexible positioning: 6 different positions (top/bottom-left/center/right)
• ⏱️ Auto-dismiss: Configurable duration with auto-removal
• 🎯 Programmatic API: Use via composable or global plugin
• ♿ Accessible: ARIA labels and proper semantic markup
• 📱 Responsive: Works on mobile and desktop
• 🎨 Customizable: Style with CSS custom properties
• 🧪 TypeScript: Full TypeScript support
• 🌳 Tree-shakable: Only import what you need

Installation

npm install @rosadorito/vue-toast
# or
yarn add @rosadorito/vue-toast
# or
pnpm add @rosadorito/vue-toast

Quick Start

1. Install the Plugin

import { createApp } from 'vue'
import App from './App.vue'
import VueToast from '@rosadorito/vue-toast'

const app = createApp(App)
app.use(VueToast)
app.mount('#app')

2. Add VueToast Component Once

Add <VueToast /> once in your main app component:

<!-- App.vue -->
<template>
  <div id="app">
    <VueToast /> <!-- Add this once -->
    <router-view />
    <!-- or your main content -->
  </div>
</template>

3. Use Toasts Anywhere

Now you can use toasts anywhere in your app:

Using Composables (Recommended):

<template>
  <button @click="showToast">Show Toast</button>
</template>

<script setup>
import { useToast } from '@rosadorito/vue-toast'

const toast = useToast()

const showToast = () => {
  toast.success('Operation completed successfully!')
  
  // With options
  toast.error('Something went wrong!', {
    duration: 3000,
    position: 'top-center',
  })
}
</script>

Using Global $toast (Options API):

<template>
  <button @click="showToast">Show Toast</button>
</template>

<script>
export default {
  methods: {
    showToast() {
      this.$toast.success('Operation completed!')
    }
  }
}
</script>

That's it! No manual rendering, no template logic, no event handling required.

API Reference

Toast Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | message | string | Required | The message to display | | type | 'success' \| 'error' \| 'warning' \| 'info' \| 'default' | 'default' | Toast type | | duration | number | 5000 | Duration in milliseconds (0 for no auto-dismiss) | | position | ToastPosition | 'top-right' | Position on screen | | dismissible | boolean | true | Whether to show close button | | id | string | Auto-generated | Unique identifier | | onClose | () => void | - | Callback when toast closes | | onClick | () => void | - | Callback when toast is clicked |

Toast Positions

type ToastPosition =
  | 'top-left'
  | 'top-center'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-center'
  | 'bottom-right'

useToast() Composables

const {
  // State
  toasts,           // Array of all toasts
  groupedToasts,    // Toasts grouped by position
  
  // Methods
  addToast,         // Add a toast with custom options
  removeToast,      // Remove a toast by id
  clearToasts,      // Remove all toasts
  
  // Convenience methods
  success,          // Add success toast
  error,            // Add error toast
  warning,          // Add warning toast
  info,             // Add info toast
} = useToast(defaultPosition?: ToastPosition)

Global Plugin API

When installed as a plugin, $toast is available on Vue instances:

// In Options API
this.$toast.success('Message')

// In Composition API setup()
import { getCurrentInstance } from 'vue'

const instance = getCurrentInstance()
instance?.proxy?.$toast.success('Message')

Methods available on $toast:

• success(message, options?)
• error(message, options?)
• warning(message, options?)
• info(message, options?)
• add(options)

Styling

CSS Custom Properties

You can customize the appearance using CSS custom properties:

:root {
  --vue-toast-border-radius: 6px;
  --vue-toast-padding: 12px 16px;
  --vue-toast-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --vue-toast-font-size: 14px;
  --vue-toast-line-height: 1.4;
  --vue-toast-box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

/* Type-specific colors */
.vue-toast--success {
  --vue-toast-border-color: #10b981;
  --vue-toast-bg-color: #f0fdf4;
  --vue-toast-text-color: #065f46;
}

.vue-toast--error {
  --vue-toast-border-color: #ef4444;
  --vue-toast-bg-color: #fef2f2;
  --vue-toast-text-color: #991b1b;
}

Overriding Styles

You can override the default styles by targeting the component classes:

.vue-toast {
  /* Your custom styles */
}

.vue-toast__close {
  /* Custom close button styles */
}

TypeScript

Full TypeScript support is included. Import types as needed:

import type { ToastOptions, ToastPosition, ToastType } from '@rosadorito/vue-toast'

Examples

Multiple Toasts with Different Positions

<template>
  <div>
    <button @click="addTopLeft">Top Left</button>
    <button @click="addBottomCenter">Bottom Center</button>
    
    <div v-for="(toasts, position) in groupedToasts" :key="position">
      <VueToast
        v-for="(toast, index) in toasts"
        :key="toast.id"
        :toast="toast"
        :index="index"
        :total="toasts.length"
        @close="removeToast(toast.id)"
      />
    </div>
  </div>
</template>

<script setup>
import { useToast } from '@rosadorito/vue-toast'

const { addToast, removeToast, groupedToasts } = useToast()

const addTopLeft = () => {
  addToast({
    message: 'Top left notification',
    type: 'info',
    position: 'top-left',
    duration: 3000,
  })
}

const addBottomCenter = () => {
  addToast({
    message: 'Bottom center warning',
    type: 'warning',
    position: 'bottom-center',
    duration: 5000,
  })
}
</script>

Toast with Callbacks

const showToastWithCallback = () => {
  addToast({
    message: 'Click me!',
    type: 'success',
    onClick: () => {
      console.log('Toast clicked!')
      // Navigate or perform action
    },
    onClose: () => {
      console.log('Toast closed')
      // Cleanup or tracking
    },
  })
}

Browser Support

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

License

MIT