TODOvue Alert (TvAlert)

A flexible, framework‑agnostic Vue 3 alert/notification component with multiple positions, types, progress bar, pause on hover, and customization utilities. Ship it in Single Page Apps or Server-Side Rendered (SSR) environments (e.g. Nuxt 3) with zero DOM assumptions.

Demo: https://ui.todovue.blog/alert

Table of Contents

• Features
• Installation
• Quick Start (SPA)
• Nuxt 3 / SSR Usage
• Component Registration Options
• Props
• Alert Options
• Composable API (useAlert)
• Positions
• Alert Types
• Customization (Styles / Theming)
• Accessibility
• SSR Notes
• Development
• Contributing
• License

Features

• Multiple alert types: info, success, warning, error
• Six position options: top-right, top-center, top-left, bottom-right, bottom-center, bottom-left
• Auto-dismiss with customizable duration
• Progress bar showing remaining time
• Pause on hover (configurable)
• Optional close button
• Stack multiple alerts in the same position (with max limit)
• Programmatic API via composable (useAlert)
• Smooth slide-in/slide-out transitions
• Works in SPA and SSR (Nuxt 3) contexts
• Tree-shake friendly (Vue marked external in library build)

Installation

Using npm:

npm install @todovue/tv-alert

Using yarn:

yarn add @todovue/tv-alert

Using pnpm:

pnpm add @todovue/tv-alert

Quick Start (SPA)

Global registration (main.js / main.ts):

import { createApp } from 'vue'
import App from './App.vue'

import '@todovue/tv-alert/style.css'
import { TvAlert } from '@todovue/tv-alert'

const app = createApp(App)
app.component('TvAlert', TvAlert)
app.mount('#app')

In your root component (App.vue):

<template>
  <div id="app">
    <TvAlert />
    <router-view />
  </div>
</template>

Using the alert in any component:

<script setup>
import { useAlert } from '@todovue/tv-alert'

const { api } = useAlert()
const alert = api()

function showNotification() {
  alert.success('Operation completed successfully!')
}
</script>

<template>
  <button @click="showNotification">Show Alert</button>
</template>

Nuxt 3 / SSR Usage

Step 1: Add the stylesheet to your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    '@todovue/tv-alert/nuxt'
  ]
})

Step 2: Create a plugin file: plugins/tv-alert.client.ts (client-only is fine, or without suffix for SSR as it is safe):

import { defineNuxtPlugin } from '#app'
import { TvAlert } from '@todovue/tv-alert'

export default defineNuxtPlugin(nuxtApp => {
  nuxtApp.vueApp.component('TvAlert', TvAlert)
})

Step 3: Add the component to your app.vue or layout:

<template>
  <div>
    <TvAlert />
    <NuxtPage />
  </div>
</template>

Use anywhere:

<script setup>
import { useAlert } from '@todovue/tv-alert'

const { api } = useAlert()
const alert = api()

function notify() {
  alert.info('Welcome to our app!')
}
</script>

Component Registration Options

| Approach | When to use | |-------------------------------------------------------------------|------------------------------------------------| | Global via app.use(TvAlert) | Recommended - single instance across app | | Local named import { TvAlert } | When you need multiple alert containers | | Direct default import import TvAlert from '@todovue/tv-alert' | Single usage or manual registration |

Props

The TvAlert component accepts the following props:

| Prop | Type | Default | Description | |------|--------|---------|--------------------------------------------------| | max | Number | 8 | Maximum number of alerts to display per position |

Example:

<TvAlert :max="5" />

Alert Options

When calling alert.open() or type-specific methods, you can pass an options object:

| Option | Type | Default | Description | |---------------|---------|--------------|-------------------------------------------------------| | title | String | null | Optional bold title above the message | | message | String | '' | The message to display in the alert | | type | String | 'info' | Alert type: 'info', 'success', 'warning', or 'error' | | position | String | 'top-right' | Position of the alert (see Positions section) | | duration | Number | 4000 | Duration in milliseconds (0 = never auto-dismiss) | | showClose | Boolean | true | Show/hide close button | | pauseOnHover | Boolean | true | Pause auto-dismiss timer on mouse hover | | showProgress | Boolean | true | Show/hide progress bar | | icon | String | null | Custom icon implementation (not widely used) | | customIcon | String | null | SVG/HTML string for a custom icon replacing default | | actions | Array | [] | Array of action buttons: { label, handler(item) } | | allowHtml | Boolean | false | Allow HTML content in the message |

Example:

alert.open({
  message: 'Custom alert',
  type: 'warning',
  position: 'bottom-center',
  duration: 6000,
  showClose: true,
  pauseOnHover: true,
  showProgress: true
})

Composable API (useAlert)

The useAlert composable provides methods to manage alerts programmatically:

import { useAlert } from '@todovue/tv-alert'

const { api, addAlert, removeAlert, clearAll, alerts } = useAlert()

// Get the simplified API
const alert = api()

// Type-specific methods
alert.info('Information message')
alert.success('Success message')
alert.warning('Warning message')
alert.error('Error message')

// Generic method with full options
alert.open({
  message: 'Custom alert',
  type: 'info',
  position: 'top-center',
  duration: 5000
})

// Direct methods
addAlert({ message: 'Direct call', type: 'success' })
clearAll() // Remove all alerts

// Access reactive alerts array
console.log(alerts.value) // Array of current alerts

API Methods

| Method | Parameters | Returns | Description | |-----------------|------------------|---------|--------------------------------------| | api() | none | Object | Returns simplified alert API | | alert.info() | message, options | Number | Show info alert, returns alert ID | | alert.success() | message, options | Number | Show success alert, returns alert ID | | alert.warning() | message, options | Number | Show warning alert, returns alert ID | | alert.error() | message, options | Number | Show error alert, returns alert ID | | alert.open() | options | Number | Show alert with custom options | | addAlert() | options | Number | Add alert directly | | removeAlert() | id | void | Remove specific alert by ID | | clearAll() | none | void | Remove all alerts |

Positions

TvAlert supports six different positions:

• top-right (default)
• top-center
• top-left
• bottom-right
• bottom-center
• bottom-left

Example:

alert.success('Top left notification', { position: 'top-left' })
alert.warning('Bottom center notification', { position: 'bottom-center' })

Alert Types

Four alert types are available, each with its own color scheme:

• info - Blue themed (informational messages)
• success - Green themed (success/completion messages)
• warning - Orange/Yellow themed (warning messages)
• error - Red themed (error/critical messages)

Examples:

alert.info('This is an information alert')
alert.success('Operation completed successfully!')
alert.warning('Please review your input')
alert.error('An error occurred')

Customization (Styles / Theming)

The component uses SCSS variables for theming. You can customize the appearance by overriding the CSS variables or by modifying the SCSS variables:

Colors are automatically applied based on the alert type. The component includes:

• Type-specific background colors
• Progress bar animations
• Smooth slide transitions
• Hover effects

For advanced customization, you can override the CSS classes:

.tv-alert {
  /* Custom styles */
}

.tv-alert--success {
  /* Custom success styles */
}

.tv-alert__progress-bar {
  /* Custom progress bar */
}

Accessibility

• Each alert container has aria-live="polite" for screen reader announcements
• Individual alerts have role="status" for proper ARIA semantics
• Close buttons include aria-label for accessibility
• Keyboard navigation supported (close button is focusable)

SSR Notes

• No direct DOM (window / document) access in source → safe for SSR
• Styles are automatically applied when you import the library
• Works seamlessly with Nuxt 3 and other SSR frameworks
• The composable uses Vue's reactivity system, compatible with SSR

Development

git clone https://github.com/TODOvue/tv-alert.git
cd tv-alert
npm install
npm run dev     # run demo playground
npm run build   # build library

Local demo served from Vite using index.html + src/demo examples.

Contributing

PRs and issues welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

License

MIT © TODOvue

Attributions

Crafted for the TODOvue component ecosystem