Vue Toasts Lite

A lightweight toast notifications library for Vue 3.

📖 Check docs

Features

• 🚀 Lightweight and easy to use
• 🎨 Multiple toast types (success, error, loading, warn, info)
• 📍 Multiple positions (can show in different corners simultaneously)
• ⚡️ Customizable duration, auto-close, and styling
• 🎯 TypeScript support
• 🎯 Promise support
• 🖱️ Pause on hover

Quick Start

1. Install the package:

npm install vue-toasts-lite

2. Add ToastsLiteProvider & vue-toasts-lite/style.css to app:

<script setup>
import { ToastsLiteProvider } from 'vue-toasts-lite'
import 'vue-toasts-lite/style.css'
</script>

<template>
  <div>
    <RouterView />
    <ToastsLiteProvider />
  </div>
</template>

3. Use anywhere in your app:

<script setup>
import { toasts } from 'vue-toasts-lite'

toasts.success('Hello!')
toasts.error('Something went wrong')
toasts.loading('Loading...')
toasts.warn('Warning message')
toasts.info('Info message')
</script>

API

// Basic methods
toasts.success(message, options?)
toasts.error(message, options?)
toasts.loading(message, options?)
toasts.warn(message, options?)
toasts.info(message, options?)

// Advanced methods
toasts.add(options)              // Create custom toast
toasts.update(id, options)       // Update existing toast
toasts.remove(id?)               // Remove toast(s)
toasts.clear()                   // Clear all toasts
toasts.promise(promise, options) // Handle promise states

// Monitoring methods
toasts.toastList                 // Get array of all active toasts
toasts.onToastsListChange(callback) // Subscribe to toast list changes

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | message | string | - | Message to display | | type | 'success' \| 'error' \| 'loading' \| 'warn' \| 'info' | 'success' | Toast type | | duration | number | 3000 | Duration in milliseconds | | autoClose | boolean | true | Auto-close behavior | | position | ToastPosition | 'top-center' | Toast position | | closable | boolean | true | Show × button and allow body click to dismiss | | id | string | auto | Custom ID |

Available Positions

top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, middle-center

Examples

Basic Usage

// With options
toasts.success('Success!', { duration: 5000, position: 'bottom-right' })

// Multiple positions at once
toasts.success('Top', { position: 'top-center' })
toasts.error('Bottom', { position: 'bottom-right' })

Update Toasts

const id = toasts.loading('Uploading...')
// Later
toasts.update(id, { type: 'success', message: 'Done!' })

Promise Support

await toasts.promise(
  fetchData(),
  {
    loading: 'Loading...',
    success: 'Loaded!',
    error: 'Failed!'
  }
)

Closable & Close Button

The closable flag (default true) controls both the × button on the right and click-to-dismiss on the toast body. When false, the toast can only be closed by the auto-close timer or programmatically via toasts.remove(id).

// Default — × button visible, body click closes
toasts.success('Saved')

// Sticky — no button, no body click, no timer
toasts.warn('Sticky', { autoClose: false, closable: false })

// No timer but user can still dismiss via × or body click
toasts.info('Click to dismiss', { autoClose: false, closable: true })

// Auto-close only, no × button
toasts.success('Timer-only', { closable: false })

To hide the × button on every toast at once without disabling click-to-dismiss, pass hide-close-button to the provider:

<ToastsLiteProvider :hide-close-button="true" />

Per-toast closable: false always wins — no button, no body click, no dismiss.

Styling

Customize colors and appearance with CSS variables or by passing custom classes to ToastsLiteProvider:

Custom Classes

You can pass custom classes to ToastsLiteProvider:

<ToastsLiteProvider 
  container-class="custom-container"
  wrapper-class="custom-wrapper"
  item-class="custom-item"
/>

• container-class - class for toast container
• wrapper-class - class for toast wrapper
• item-class - class for individual toast items

CSS Variables

:root {
  --tl-font-family: system-ui, -apple-system, sans-serif;
  --tl-font-size: 14px;
  --tl-radius: 8px;
  --tl-bg: hsl(0, 0%, 100%);
  --tl-text: hsl(0, 0%, 20%);
  --tl-border: hsl(0, 0%, 85%);
  --tl-shadow: hsla(0, 0%, 0%, 0.1);
  --tl-success: hsl(145, 63%, 42%);
  --tl-error: hsl(0, 79%, 63%);
  --tl-warn: hsl(45, 100%, 51%);
  --tl-info: hsl(210, 80%, 55%);
  --tl-icon-color: hsl(0, 0%, 100%);
  --tl-spinner-color: hsl(0, 0%, 15%);

  --tl-bg-success: color-mix(in srgb, var(--tl-success) 20%, var(--tl-bg));
  --tl-bg-error: color-mix(in srgb, var(--tl-error) 20%, var(--tl-bg));
  --tl-bg-warn: color-mix(in srgb, var(--tl-warn) 20%, var(--tl-bg));
  --tl-bg-info: color-mix(in srgb, var(--tl-info) 20%, var(--tl-bg));
  --tl-bg-loading: var(--tl-bg);

  --tl-border-success: color-mix(in srgb, var(--tl-success) 40%, var(--tl-border));
  --tl-border-error: color-mix(in srgb, var(--tl-error) 40%, var(--tl-border));
  --tl-border-warn: color-mix(in srgb, var(--tl-warn) 40%, var(--tl-border));
  --tl-border-info: color-mix(in srgb, var(--tl-info) 40%, var(--tl-border));

  --tl-text-success: color-mix(in srgb, var(--tl-success) 20%, var(--tl-text));
  --tl-text-error: color-mix(in srgb, var(--tl-error) 20%, var(--tl-text));
  --tl-text-warn: color-mix(in srgb, var(--tl-warn) 20%, var(--tl-text));
  --tl-text-info: color-mix(in srgb, var(--tl-info) 20%, var(--tl-text));
  --tl-text-loading: var(--tl-text);
}

License

MIT