Full-featured Cross-platform Notification System – Notivue

Install & Download:

# Yarn
$ yarn add notivue
# NPM
$ npm i notivue

Description:

Notivue is a fully-featured, lightweight, and accessible notification system designed exclusively for Vue and Nuxt.  It packs various options and boasts an impressive selection of 5 themes – Light, Pastel, Material, Dark, and Slate – as well as 4 notification types: Success, Error, Warn, and Info.

The Notivue component flaunts slick transitions and animations, all of which can be fully customized to your liking, adding that extra charm to your notifications. You can also make use of the Custom Components API to incorporate your components, letting Notivue take care of the rest.

For those moments when you need to update pending notifications, Notivue comes with an easy-to-use Promise API, providing an effortless way to manage your notification statuses.

How to use it:

1. Import and register the Notivue.

// Vite
import { createApp } from 'vue'
import { createNotivue } from 'notivue'
import App from './App.vue'
// Only needed if using built-in notifications
import 'notivue/notifications.css' 
// Only needed if using built-in animations
import 'notivue/animations.css' 
const notivue = createNotivue({
  // options here
})
const app = createApp(App)
app.use(notivue)
app.mount('#app')
// Nuxt
export default defineNuxtConfig({
  modules: ['notivue/nuxt'],
  css: [
    'notivue/notifications.css',
    'notivue/animations.css'
  ],
  notivue: {
    // Options here
  }
})

2. Enable a button to toggle a basic notification.

// App.vue
<script setup>
  import { Notivue, Notifications, push } from 'notivue'
</script>
<template>
  <button @click="push.success('A basic notification!')">
    Push
  </button>
  <Notivue v-slot="item">
    <Notifications :item="item" />
  </Notivue>
</template>
// app.vue (Nuxt)
<template>
  <button @click="push.success('A basic notification!')">
    Push
  </button>
  <Notivue v-slot="item">
    <Notifications :item="item" />
  </Notivue>
</template>

3. All possible notification types:

push.success({
  title: 'Notification Title',
  message: 'Success message.'
})
push.error('Error message.')
push.warning('Warning message.')
push.info('Info message.')

4. Dismiss the notifications manually.

notification.clear() 
notification.destroy()
notification.clearAll() 
notification.destroyAll()

5. Create a Primose notification.

async function sendMessage() {
  const notification = push.promise("We're sending your message, hold on...")
  try {
    await new Promise((resolve, reject) =>
      setTimeout(Math.random() > 0.5 ? resolve : reject, 2000)
    )
    notification.resolve('Your message has been successfully sent!')
  } catch (err) {
    notification.reject(
      'There was an error sending your message. Please try again.'
    )
  }
}

6. Callback functions.

push.success({
  message: 'Welcome back, you can now access your account.',
  props: {
    myCustomProp: true
  },
  onAutoClear(item) {
    console.log(item.message) 
    console.log(item.props.myCustomProp)
  },
  onManualClear(item) {
    console.log(item.message) 
    console.log(item.props.myCustomProp) 
  }
})
const notification = push.promise({
  message: 'Sending message, please hold on...',
  onAutoClear(item) {
    console.log(item.type) 
    console.log(item.message)
  }
})
notification.resolve('Your message has been successfully sent.')

7. Apply a theme of your choice to the notifications.

import {
  lightTheme, // default
  pastelTheme,
  materialTheme,
  darkTheme,
  slateTheme
} from 'notivue'
<template>
  <Notivue v-slot="item">
    <Notifications
      :item="item"
      :theme="darkTheme" 
    />
  </Notivue>
</template>

8. Apply aniamtions to the notifications.

app.use(notivue, {
  animations: {
    enter: 'slide-in',
    leave: 'slide-out',
    clearAll: 'fade'
  }
})

9. Append icons to the notifications.

import {
  filledIcons, // default
  outlinedIcons
} from 'notivue'
<template>
  <Notivue v-slot="item">
    <Notifications
      :item="item"
      :icons="outlinedIcons" 
    />
  </Notivue>
</template>

10. Available options.

export const success: NotificationOptions = {
   title: '',
   message: '',
   duration: DEFAULT_DURATION,
   ariaLive: 'polite',
   ariaRole: 'status',
}
const error: NotificationOptions = {
   ...success,
   ariaLive: 'assertive',
   ariaRole: 'alert',
}
const promise: NotificationOptions = {
   ...success,
   duration: Infinity,
}
const warning: NotificationOptions = {
   ...error,
   ariaLive: 'polite',
}
const info: NotificationOptions = {
   ...success,
}
export const defaultNotificationOptions = {
   [NKeys.SUCCESS]: success,
   [NKeys.ERROR]: error,
   [NKeys.WARNING]: warning,
   [NKeys.INFO]: info,
   [NKeys.PROMISE]: promise,
   [NKeys.PROMISE_RESOLVE]: success,
   [NKeys.PROMISE_REJECT]: error,
} as NotificationOptionsField

Preview:

Full-featured Cross-platform Notification System Notivue

Changelog:

v2.4.0 – v2.4.3 (04/15/2024)

  • New: useNotivueInstance. Consumers can now fully control the Notivue instance by stopping and restarting it.
  • Change: Add transition config property and disable automatic transition property detection
  • Improvement: Fine-tune repositioning
  • Improvement: Fine-tune ResizeObserver
  • Improvement: Fine-tune pauseOnTabChange: false
  • Fix: syncTransitionStyles edge case failure

v2.3.0 (04/06/2024)

  • New (Core): Add avoidDuplicates config option
  • New (Core): Expose isStreamPaused internal signal
  • New (Built-in Notifications): Add NotificationProgress drop-in component
  • Refactor (Core): Use window’s focus/blur events instead of visibilityChange
  • Improve (Core): Remove workaround for lightningcss keyframes minification (fixed upstream)
  • Improve (Core): Add singular-named import aliases for any exported CSS file
  • Fix (Built-in Notifications): Fix setting fallback accent color when computing –nv-accent CSS variable

v2.2.1 (02/05/2024)

  • Replace SVG spinner <animate> with pure CSS keyframes animation.
  • Add –nv-y-align-has-title theme variable. It is now possible to set a different vertical align that only applies to notifications with title. The variable is set to center by default.

v2.2.0 (01/29/2024)

  • It is now possible to disable the built-in Teleport feature by passing false to the teleportTo config option
  • Refactor timeouts handling

v2.2.0 (01/09/2024)

  • Refactor

v2.1.1 (01/09/2024)

  • Refactor

v1.4.5 (12/26/2023)

  • Refactor

v1.4.5 (12/09/2023)

  • Import Nuxt composables from #imports instead of #app.
  • Fix teleportTo prop not working with HTML elements.

v1.4.3/4 (11/01/2023)

  • NotivueSwipe – Improved stream pausing/resuming after touch interactions. Interactions that may trigger a clear or a position reset will now schedule the resumal using debounce instead of immediately performing it.
  • NotivueSwipe – Fix isPointerInside computation, which paused the stream after releasing a notification if the mouse pointer was still hovering a notification.
  • NotivueCore – Added will-change: transform when repositioning the notifications. This improves performance on Android Firefox which was the only environment “suffering” from it since the last minor release.
  • Bugfixes

v1.4.2 (10/18/2023)

  • Notivue, NotivueKeyboard – Both exported components are now wrapped in a ClientOnly component by default. Before this release, this was only applied to the Nuxt module auto-imported components. However, this would have thrown SSR errors for users either importing them directly in a Nuxt app via import statements or for users using non-nuxt SSR solutions (such as vite-plugin-ssr).
  • Notivue Core – Configuration properties have been converted from shallow refs to refs. This reduces a bit the bundle size and removes the requirement of calling triggerRef when updating nested properties such as config.notifications.global.
  • Nuxt Module – Streamlined type modules declaration and removed client-only versions of Notivue and NotivueKeyboard as they’re now unneccessary.
  • NotivueKeyboard – Lowered the default value of maxAnnouncements prop from 3 to 2.
  • Package – The bundled output now only includes JavaScript APIs not greater than ES2015. While this wasn’t a problem on fresh Vite/Nuxt projects, it definetely was for users still using Vue CLI and lower output targets.

v1.4.1 (10/09/2023)

  • Fixed a bug where global notification duration set in Notivue Config was also applied to promises (which should always be set to Infinity)

v1.4.0 (09/30/2023)

  • Core – Updated default enter/leave animations with a more visually appealing pair. If you still wish to use the previous ones, paste this code in a new css file and replace: import ‘notivue/animations.css’ with your file path.
  • Built-in Notifications – Added an elevation effect to the close button on hover.
  • Core – Refactored the logic to get/set prefers-reduced-motion and transitionData. They are now only updated when appropriate, improving performance.
  • Notivue – Refactored the logic to add the clearAll class to the wrapper element. Now this is done the “vue-way” by passing a reactive value to the attribute, instead of using classList.add.
  • NotivueSwipe – NotivueSwipe now doesn’t call anymore item.clear method when the swipe threshold is met. Instead it first transitions the opacity to 0, then it calls item.destroy. This ensures that the leave animation is never called while providing an overall better UX.
  • Core – Streamlined the store by removing some unnecessary code, reducing by little the bundle size.
  • Bugfixes

v1.3.3 (09/17/2023)

  • Fixed a regression introduced in v1.3.0 where repositioning was not invoked properly when an element was pushed from the queue.
  • Removed unnecessary configuration watcher in createNotivue.

v1.3.2 (09/16/2023)

  • NotivueSwipe: You can now choose which method to call when clearing the notification via the new destroy prop. By default is set to false which means that the leave animation will be played when clearing.
  • Notivue Core: Fixed a bug where queued promises were not updated properly due to a regression introduced in v1.3.0

v1.3.1 (09/12/2023)

  • Add addPlugin boolean to module options. This won’t initialize the notivue store via createNotivue leaving to you the implementation while still providing auto imports. Can be used for example, to export the push reference if using ssr: false.
  • The push object is now frozen to prevent accidental tampering.
  • Bugfixes

v1.3.0 (09/11/2023)

  • Direct push in Vite SPA (Single-page apps)
  • Notivue now ships with a nuxt module that you can add to your nuxt config, it provides automatic plugin installation, auto imports and built-in client-only mounting of Notivue root components.
  • Add onAutoClear and onManualClear push callbacks

v1.2.4 (08/20/2023)

  • You can now pass a ref to both message and title push options.
  • Add hideClose prop, which is by default set to false. This can be handy if you’re lazy, and you don’t want to import, clone and edit the icons object.
  • Add maxAnnouncements prop, which is by default set to 3. Leave notifications that announce the exit from the stream and the ability to re-enter using the combination key are now pushed only the first three times.
  • Set the default width of the notification container to auto. After taking a look at the projects using Notivue, I noticed that the majority of the users are pushing notifications with very short messages.
  • For the same reason, increased default font size from 0.925 to 1 rems and default spacing from 0.5 to 0.625 rems.
  • Slightly darkened materialTheme background colors to improve accessibility and match WCAG 2 Contrast and Color Requirements.
  • Fix leave announcements to be pushed to the stream if pressing Tab after focusing the stream with a device different from the keyboard.

v1.2.3 (08/18/2023)

  • Bugfixes

v1.2.2 (08/16/2023)

  • Refactored the configuration types, which were causing a Vue bug where NotivueConfig type couldn’t be imported in an SFC because of a complex generic that vue-sfc-compiler couldn’t process.
  • NotivueSwipe – Force touch-action: none on any child of the notification.
  • NotivueKeyboard – Fixed useLastFocused composable, which was returning a wrong element.
  • NotivueSwipe – Functionalities are now automatically disabled if the item has its duration set to Infinity.
  • NotivueKeyboard – Improved queue support.

v1.2.0 (08/15/2023)

  • Added support for enqueuing notifications using the enqueue config option. By defining a limit and enqueue: true, notifications will be queued once the limit is reached and displayed one-by-one as soon as a previous notification is dismissed.
  • Added skipQueue push option to skip the queue and display the notification immediately.
  • Added ariaLiveOnly to push options. This allows to push a notification without displaying it, but only making it available to screen readers.
  • Drop-In Components: Notivue now ships with two new drop-in components: NotivueKeyboard and NotivueSwipe.
  • Notivue now exports a useNotifications composable, which allows you to access a read-only reactive array of all displayed and queued notifications. It can be used to create side effects.
  • Timeout handling logic has been rewritten from scratch, considering all of the above new features and interactions.
  • Minification step is now performed by esbuild instead of terser (using Vite defaults). This increases by very little the whole bundle size, but improves my DX a lot.
  • Disabled keyboard navigation and removed focus styles on the dismiss button.
  • Slightly darkened darkTheme colors.
  • Bugfixes.

v1.1.4 (08/03/2023)

  • Bugfixes

v1.1.3 (07/27/2023)

  • Fixed a bug where enter/leave/clearAll animations were played if setting prefers-reduced-motion to reduce from System Settings after mount.

v1.1.2 (07/24/2023)

  • Update

v1.1.1 (07/23/2023)

  • Added margin: auto to the notifications’ stream left and right margin. This fixes a bug where the stream was not centered when using a custom –nv-root-width.
  • Removed filter: blur to push.clearAll animation.
  • Added check to clear the pauseOnTouch timeout on before unmount.

v1.1.0 (07/21/2023)

  • Notifications are now paused and resumed when focusing with the keyboard any button in the notification. This is done automatically whether you’re using built-in notifications or custom components.
  • Types are now generated using vite-plugin-dts rollupTypes flag. Notivue now ships with a single declaration file instead of relying on multiple files (and imports).
  • pauseOnTouch logic has been streamlined and updated. When tapping on a notification, the stream is paused for 2 seconds, then timeouts are resumed. Timeouts can be paused again only after they are resumed, ensuring an overall better UX and support for swipe gestures.
  • The above-mentioned improvement adds support for clear on swipe gesture using NeoDrag. This feature is not included in the package and must be installed manually. A guide has been published to the documentation website.
  • lightTheme foreground color and shadow have been updated. Shadow is now less invasive, and the foreground color has been updated from a slate to a neutral black.
  • Icons overflow has been set to visible to avoid some pixels cut-off in some edge cases on low resolution devices.
    Container width has been reduced from 360px to 350px.

Add Comment