@calumk/vue-progress-status NPM

@calumk/vue-progress-status

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

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