vue3-notifier

vue3-notifier is a powerful notification plugin with a very easy to use interface and high customizability as we gonna discuss in the rest of documentation.

Installation

# Using yarn
yarn add vue3-notifier

# Using npm
npm i vue3-notifier --save

Usage

// main.ts
import 'vue3-notifier/style.css';

import { createApp } from 'vue';
import { useNotifierPlugin } from 'vue3-notifier';

import App from './App.vue';

createApp(App)
  .use(useNotifierPlugin())

  .mount('#app');

// App.vue
import { useNotifier } from 'vue3-notifier';

const notifier = useNotifier();
notifier.notify();

Examples

Example are add in docs/examples.md Find More!

API Documentation

Note: All props are optionals as the plugin provide a default value for every prop so that you only need to pass as minial config as possible.

NotifierPluginOptions

Prop	type	default	Description
id	String	"default"	id is used while initializing useNotifierPlugin which provide a unique key to allow using plugin more than once.
timeout	number	3_000	A number in ms that indicates the time before the notifiction gets destroied.
persistent	boolean	false	Indicates that notification shouldn't be automatically destroied.
newOnTop	boolean	false	Indicates new notifications should be on top or not.
maxNotifictions	number	3	Max allowed number of notifictions to be shown at once on screen.
component	NotifierComponent	DefaultNotifier.vue	A vue component which will be rendered as a notifiction.
props	Record<string, any>	{}	Extra props to be passed to notification component.
plugins	Plugin[]	[]	A set of plugins which injected to notifier app.
showProgressBar	boolean	false	Toggle visability; true -> visible, false -> hidden.
closable	boolean	true	Toggle visability of close button.
pauseOnHover	boolean	true	Toggle pausing time when user hover over notification; this is extremly useful to improve ux.
position	'top' | 'top center' | 'top left' | 'top right' | 'bottom' | 'bottom center' | 'bottom left' | 'bottom right' | 'center' | 'center center'	"bottom right"	Indicates position of notifications container.
closeButton	NotifierComponent	DefaultCloseBtn.vue	A vue component that will be used as a close button.
showCloseButtonOnHover	boolean	false	If true then close button will be hidden untill the user hover over notification.
debug	boolean	false	Enables some logs for debugging (recommended to be enabled in development import.meta.env.DEV || process.env.NODE_ENV === 'development').
silent	boolean	false	Avoid throwing error while initializing if something went wrong.
logger	Partial<NotifierLogger>	logger	Logger which will be used in debug mode.
containerOffset	number	20	Offset between container holding notifications and the edges of the screen (in px).
containerWidth	number	350	Notifications' container width (in px).
containerClassList	string[]	[]	Classlist will be appended to notifications' container.
containerStyles	StyleValue	{}	Styles will be added to notifications' container.
notificationOffset	number	20	Gap between each notification.
notificationClassList	string[]	[]	ClassList will be appended to each notification.
notificationStyles	StyleValue	{}	Styles will be added to each notification.
hideAllButton	NotifierComponent	HideAllBtn.vue	Append a button which hide all notfications.
showHideAllButton	boolean	true	Toggle visability of hide all button.

NotifierOptions

Note: The following props are exactly the same as above so we won't mention them in NotifierOptions api.

timeout, persistent, component, props, showProgressBar, closable, pauseOnHover, closeButton, showCloseButtonOnHover, notificationClassList, notificationStyles.

prop	type	default	description
title	string	""	Title to show on notifiction supports html.
description	string	""	Text to be render in notifiction supports html.
showIcon	boolean	true	Toggle icon visability; true -> show icon, false -> hide icon.
icon	NotifierComponent	DefaultIcon.vue	A vue to be used as notificaiton's icon.
type	'default' | 'info' | 'warning' | 'success' | 'error'	"default"	type of the notification.

NotifierService

method	params	returns	description
updatePluginOptions	(options?: NotifierPluginOptions)	void	Allow to update plugin options after initializing; Note: not all options can be updates as they require reinitializing the plugin (e.g: plugins).
notify	(options?: NotifierOptions)	Required<NotifierOptions & NotifierExtraOptions>	Open a new notification with the specified options.
destroy	(id: number)	boolean	Destroy notification using it's id.
destroyAll	()	void	Destroy all notifications in that specific app.

Props Helpers

method	propName	type	description
makePluginOptionsProps	pluginOptions	Required<NotifierPluginOptions>	Defines prop for plugin global options.
makeNotifierServiceProps	notifierService	NotifierService	Desfines prop for notifier service.
makeNotificationProps	notification	Required<NotifierOptions & NotifierExtraOptions>	Defines prop for notification.

Note: makeNotifierProps is a combine of the 3 above methods.

Composables

method	params	return	description
useNotifierPlugin	(options?: NotifierPluginOptions)	Plugin	Creates a new notifier app with specific id.
useNotifier	(id: string = 'default')	NotifierService	Get the service of the notifier app with that specific id.

Hooks

hook	params	return	description
useDestroyTimer	(options: Required<NotifierOptions & NotifierExtraOptions>,globalOptions: Required<NotifierPluginOptions>,onFinish: () => void)	ComputedRef<{value: number;pauseTimeout: () => void;resumeTimeout: () => void }>	A helper hook to count down for timeout of destroying a notification also providing pause/resume method to allow stop/continue of timeout.