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. |