Notification

Notification is a Vue 3 plugin for managing notification.

Installation

Note: this package require animejs and shortid npm package.

CDN

This package published as vNotif module in umd.

<link
  rel="stylesheet"
  href="https://unpkg.com/@termehui/vnotif/dist/style.css"
/>
<script src="https://unpkg.com/@termehui/vnotif"></script>

NPM

npm i @termehui/vnotif

Install notification container with default name (notification):

import { createApp } from "vue";
import App from "./App.vue";
import vNotif from "@termehui/vnotif";

createApp(App).use(vNotif).mount("#app");

Install notification container with custom name:

import { createApp } from "vue";
import App from "./App.vue";
import { Container } from "@termehui/vnotif";
createApp(App).component("notif-container", Container).mount("#app");

Options

Notification has three level options:

• global options (used by default for all container)
• container options (passed as container property and override global options)
• notification options (passed on creation time and override container and global options)

Property	Type	Description	Default
duration	number	duration in millisecond, pass 0 to disable auto close	5000 (5 sec)
pauseDelay	number	delay in millisecond for wait before active pause mode	50
enterAnimation	AnimeParams	show animation (animejs animation option)	slide up
leaveAnimation	AnimeParams	hide animation (animejs animation option)	slide down
onAction	(key: string, data?: unknown) => Promise<boolean>	callback for handle action click	null
onClose	(mode: "auto" | "click" | "action") => void	callback for called after notification close	null

Usage

Add Notification Container

To showing notification in your app you need to add notification container component in your template.

<template>
  <notification name="default" :options="{ duration: 7000 }" />
</template>

Property	Type	Description	Default
name	string	container name	default
options	NotificationOptions	default options used for creating new notification	{}

Note: you can have multiple container in your app. every container must have a unique name.

Note: you can use createNotification and createSimpleNotification to creating notification for named container or use createDefaultNotification and createDefaultSimpleNotification to creating notification for unnamed (default) container.

Show Simple Notification

Note: simple notifications has no actions. if you want notification with actions support you must use custom notification.

Note: simple notifications accept html string as content.

Note: title is optional and you can create notification without title.

import { defineComponent } from "vue";
import { createDefaultSimpleNotification } from "@termehui/vnotif";

export default defineComponent({
  setup() {
    function showNotification() {
      const globalId = createDefaultSimpleNotification(
        {
          title: "Greeting",
          content: "Welcome to our app!",
          class: "my-custom-class",
        },
        {
          duration: 10000,
          onClose: (mode: "auto" | "click" | "action") => {
            console.log(`notification closed by ${mode} mode`);
          },
        }
      );
      console.log(`new notification by globalId: ${notificationId} created!`);
    }

    return { showNotification };
  },
});

Custom Notifications

To create custom notification you need define a normal vue component with notification library composition api helpers useNotification and create notification instance using createNotification function.

Note: by default every notification received globalId and options props. you must define this props in your components and use it to define new notification component.

Note: you can define any props in your custom notification component and pass this props when you want create new notification.

useNotification Parameters

Caution: if root element not passed notification animations doesn't work!

Parameter	Type	Description
globalId	string	global notification id (Automatically passed on create)
options	NotificationOptions	notification options (Automatically passed on create)
el	Ref<HTMLElement>	notification root node reference

useNotification Return Values

Name	Type	Description
progress	number	current progress value (when auto closed enabled)
loading	boolean	on action, loading state will active until action promise completed
action	(key: string, data?: unknown) => void	helper method to call notification action handler
close	() => void	close notification
pause	() => void	active pause mode
resume	() => void	de-active pause mode

<template>
  <div
    class="v-notification"
    @mouseenter="pause"
    @mouseleave="resume"
    ref="container"
  >
    <div class="content">
      <p>{{ message }}</p>
      <div v-if="loading">Loading...</div>
      <p>{{ progress }} <strong>%</strong></p>
      <div class="gaper is-auto">
        <div class="filler"></div>
        <button class="is-simple" @click.stop="action('no', 'data')">
          {{ noText || "no" }}
        </button>
        <button
          class="is-primary"
          :class="{ 'is-disabled': loading }"
          @click.stop="action('yes')"
        >
          {{ yesText || "yes" }}
        </button>
      </div>
    </div>
    <div
      class="v-notification-progress"
      :style="{ width: `${progress}%` }"
    ></div>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
import { NotificationOptions, useNotification } from "@termehui/vnotif";
export default defineComponent({
  name: "MyNotification",
  props: {
    globalId: {
      type: String,
      required: true,
    },
    options: {
      type: Object as () => NotificationOptions,
      required: true,
    },
    // custom props
    message: String,
    yesText: String,
    noText: String,
  },
  setup(props) {
    const container = ref<HTMLElement>(); // template ref
    const { progress, loading, action, close, pause, resume } = useNotification(
      props.globalId,
      props.options,
      container
    );

    return { progress, loading, action, close, pause, resume, container };
  },
});
</script>

Use Custom Notification

createNotification method parameters:

Note: when using createDefaultNotification method, container parameters not exists.

Parameter	Type	Description
container	string	container name
com	Object	component
props	Object	component props
options	NotificationOptions	notification options

Note: createNotification return new notification global id as result.

import { defineComponent } from "vue";
import { createDefaultNotification } from "@termehui/vnotif";
import MyNotification from "./MyNotification.vue";
export default defineComponent({
  setup() {
    const showNotification = () => {
      createDefaultNotification(
        MyNotification,
        {
          message: "are you want to delete record?",
          yesText: "Delete",
          noText: "Cancel",
          class: "is-error",
        },
        {
          onAction: async (k, _) => {
            if (k === "no") {
              return Promise.resolve(true);
            } else {
              const res = await doSomeLongAsyncWork();
              return res ? Promise.resolve(true) : Promise.resolve(false);
            }
          },
        }
      );
    };

    return { showNotification };
  },
});

Styling

for using default styles you can use one of static (CSS) or termeh (SCSS) predefined files.

Note: advanced feature (change default vars, padding classes and color classes) only available in termeh version of style.

// Static
@import "@termehui/vnotif/style.css";
@import "@termehui/vnotif/dist/style.css"; // old node version
// Termeh
@import "@termehui/vnotif/style.scss";
@import "@termehui/vnotif/dist/style.scss";// old node version

Container Styles

• is-left-top: position container to left top.
• is-right-top: position container to right top.
• is-center-top: position container to center top.
• is-left-bottom: position container to left bottom.
• is-right-bottom: position container to right bottom.
• is-center-bottom: position container to center bottom.
• is-sub: add this class to container when use container inside some part of ui (for non-fullscreen containers).

Note: Parent node of sub containers must have position: relative; style!

Notification Styles

Notification by default can contains following parts:

• content: contains notification content (headers, text, etc).
• progress: progress element.

Note: this elements must placed directly as child.

<div class="v-notification">
  <div class="content">
    <h1>{{ header }}</h1>
    <p>{{ content }}</p>
    <div class="gaper is-auto">
      <div class="filler"></div>
      <button class="is-simple">Cancel</button>
      <button class="is-primary">Approve</button>
    </div>
  </div>
  <div class="progress"></div>
</div>

Notification Classes

You could style your custom component by v-notification class.

• is-left-decorated: add left decorated border to notification.
• is-right-decorated: add right decorated border to notification.
• is-loading: add loading ui to notification.
• is-{gap}-gaped: set notification gap (padding and spacing) to registered iterable gaps (Termeh only).
• is-{color}: set notification color scheme to registered iterable colors (Termeh only).

Content Styles

Notification content by default can contains following parts:

• ...

  or header: notification header.

Customize Styling

You can override following pre-defined component variable to override default notification styling.

@include _var("notification", "width", 30rem);
@include _var("notification", "primary-border", (1px solid _color("primary")));

Variable	Description	Default
width	notification container width	20rem
z-index	notification container z-index	2
border	default notification border	none
shadow	default notification shadow	a soft shadow
progress	notification progress size	1px
gaps	list of non-iterable gaps to include in notification gaps	()
colors	list of non-iterable colors to include in notification colors	()
{color}-border	colored notification border	null
{color}-shadow	colored notification shadow	null