@calumk/vue-progress-status

A customizable status notification system for Vue 3 with a progress bar and hover functionality.

View Demo

Features

• Clean, minimal status notifications
• Progress bar for auto-dismissing messages
• Hover to pause/resume the timer
• Expandable messages for longer content
• Multiple message types (info, success, warning, error)
• Comprehensive history tracking of all notifications and updates
• Fully customizable via CSS variables

Installation

# npm
npm install @calumk/vue-progress-status

# yarn
yarn add @calumk/vue-progress-status

# pnpm
pnpm add @calumk/vue-progress-status

# bun
bun install @calumk/vue-progress-status

Usage

Basic Usage

// Show a notification
const id = progressStatus.push({
  title: 'Processing',
  message: 'Starting the operation...', // Preferred over 'text'
  severity: 'info',
  timeout: 5000
})

// Update the notification
progressStatus.update(id, {
  title: 'Processing',
  message: 'Operation in progress...',
  severity: 'success'
})

// Cancel the notification
progressStatus.cancel(id)

Available Options

Option	Type	Default	Description
title	string	''	The title of the notification
message	string	''	The message content (preferred)
text	string	''	The message content (deprecated, use message instead)
severity	'info' | 'success' | 'warning' | 'error'	'info'	The severity level of the notification
timeout	number	10000	Duration in milliseconds before auto-dismiss (0 for no auto-dismiss)
cancellable	boolean	true	Whether the notification can be manually dismissed

Methods

Method	Parameters	Return	Description
push	options: MessageOptions	number	Shows a new notification and returns its ID
update	id: number, options: MessageOptions	void	Updates an existing notification
cancel	id: number	void	Cancels a specific notification
cancelAll	-	void	Cancels all active notifications
getMessages	-	Message[]	Returns all active notifications
getMessageHistory	-	MessageHistoryEntry[]	Returns the history of all notifications
clearHistory	-	void	Clears the notification history

MessageOptions Interface

interface MessageOptions {
  title?: string;
  /** @deprecated Use message instead */
  text?: string;
  message?: string;
  severity?: 'info' | 'success' | 'warning' | 'error';
  timeout?: number;
  cancellable?: boolean;
}

Using the Service

You can use the service to trigger notifications from anywhere in your application. There are two ways to use it:

Method 1: Using Service Methods Directly

<script setup>
import { progressStatusService } from '@calumk/vue-progress-status'

function showServiceNotification() {
  const messageId = progressStatusService.push({
    title: 'Service Notification',
    text: 'This notification was triggered using the service',
    severity: 'info',
    timeout: 5000,
    cancellable: true
  })

  // Update the message
  progressStatusService.update(messageId, {
    text: 'Updated message text'
  })

  // Cancel the message
  progressStatusService.cancel(messageId)
}
</script>

Method 2: Using Message Object Methods

<script setup>
import { progressStatusService } from '@calumk/vue-progress-status'

function showServiceNotification() {
  const message = progressStatusService.push({
    title: 'Service Notification',
    text: 'This notification was triggered using the service',
    severity: 'info',
    timeout: 5000,
    cancellable: true
  })

  // Update the message
  message.update({
    text: 'Updated message text'
  })

  // Cancel the message
  message.cancel()
}
</script>

Don't forget to add the component somewhere in your app:

<template>
  <ProgressStatus />
</template>

<script setup>
import ProgressStatus from '@calumk/vue-progress-status'
</script>

API

Component Props

Prop	Type	Default	Description
debug	Boolean	false	Enables debug logging to console

Message Options

Option	Type	Default	Description
title	String	''	Title of the notification
text	String	''	Message content
severity	String	'info'	Type of notification ('info', 'success', 'warning', 'error')
timeout	Number	10000	Time in ms before auto-dismiss (0 for no timeout)
cancellable	Boolean	true	Whether user can dismiss the notification

Methods

Method	Parameters	Return	Description
push	options	messageId	Add a new notification
update	(id, options)	void	Update an existing notification
cancel	id	void	Dismiss a notification

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build the library
npm run build

# Build the GitHub Pages demo
npm run build:demo

# Preview the demo locally
npm run preview:demo

# Deploy to GitHub Pages
npm run deploy:demo

License

MIT License

---

Calum Knott

• Website: calumk.com
• GitHub: @calumk
• Twitter: @calumk
• Ko-fi: Buy me a coffee