Configuration

Initial configuration

Notivue is exclusively configured by passing a plain configuration object to createNotivue or to the notivue property of nuxt.config.ts:

Vite - main.js/ts

const notivue = createNotivue({
  position: 'top-right',
  limit: 4,
  enqueue: true,
  avoidDuplicates: true,
  notifications: {
    global: {
      duration: 10000
    }
  }
})

Nuxt - nuxt.config.ts

export default defineNuxtConfig({
  modules: ['notivue/nuxt'],
  notivue: {
    position: 'top-right',
    limit: 4,
    enqueue: true,
    avoidDuplicates: true,
    notifications: {
      global: {
        duration: 10000
      }
    }
  }
})

Type definitions

interface NotificationOptions {
  /** String to use as default title, an empty string doesn't render the title. */
  title?: string
  /** String to use as default message. */
  message?: string
  /** Duration of the notification. */
  duration?: number
  /** Value of `aria-live` attribute. */
  ariaLive?: 'polite' | 'assertive'
  /** Value of `role` attribute. */
  ariaRole?: 'alert' | 'status'
}

type NotificationType =
  | 'success'
  | 'error'
  | 'info'
  | 'warning'
  | 'promise'
  | 'promise-resolve'
  | 'promise-reject'

type Position =
  | 'top-left'
  | 'top-center'
  | 'top-right'
  | 'bottom-left'
  | 'bottom-center'
  | 'bottom-right'

type NotificationTypesOptions = Record<
  'global' | NotificationType,
  NotificationOptions
>

interface NotivueConfig {
  /** Whether to pause all notifications when hovering over them with mouse. */
  pauseOnHover?: boolean
  /** Whether to pause all notifications when tapping on them with touch devices. */
  pauseOnTouch?: boolean
  /** Whether to pause all notifications when switching tabs or window. */
  pauseOnTabChange?: boolean
  /** Wheter to enqueue notifications when limit is reached. */
  enqueue?: boolean
  /** Position of notifications, one of 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'. */
  position?: Position
  /** Notification options for each type. */
  notifications?: Partial<NotificationTypesOptions>
  /** Animation classes for `enter`, `leave` and `clearAll`. */
  animations?: {
    enter?: string
    leave?: string
    clearAll?: string
  }
  /** Transition property applied when repositioning notifications. Must match the pattern:
   *
   * `transform <duration> <timing-function>`
   */
  transition?: string
  /** Tag or element to which the stream will be teleported. */
  teleportTo?: string | HTMLElement | false
  /** Notifications limit. Defaults to `Infinity`. */
  limit?: number
  /** Whether to prevent duplicate notifications if already displayed. Duplicates will be announced again and their duration replaces the current one. */
  avoidDuplicates?: boolean
}

Dynamic configuration

Once the app is created, the configuration can be accessed and updated using the useNotivue composable. Each property maps to a ref that allows for reactive updates and side-effects:

<script setup>
import { watchEffect } from 'vue'
import { useNotivue } from 'notivue'

const config = useNotivue() // Or { position } = useNotivue(), reactivity won't be lost

watchEffect(() => {
  console.log('New position: ' + config.position.value)
})
</script>

For convenience the configuration can be "patched" using the update method. New options are merged to your initial configuration:

<script setup>
import { useNotivue } from 'notivue'

const config = useNotivue()

config.update({
  position: 'bottom-right',
  enqueue: true,
  notifications: {
    global: {
      duration: 10000
    }
  }
})
</script>

Alternatively, a function that returns new options and receives the current configuration as argument can be used as well:

config.update((prevConf) => {
  return {
    position: prevConf.position === 'top-right' ? 'bottom-right' : 'top-right',
    enqueue: !prevConf.enqueue,
    avoidDuplicates: !prevConf.avoidDuplicates
  }
})

To update the configuration from outside your components, use the updateConfig utility:

import { updateConfig } from 'notivue'

updateConfig({
  position: 'bottom-right',
  enqueue: true,
  notifications: {
    global: {
      duration: 10000
    }
  }
})

updateConfig((prevConf) => {
  return {
    enqueue: !prevConf.enqueue,
    avoidDuplicates: !prevConf.avoidDuplicates
  }
})

Default configuration and notification options

import type { NotivueConfig, NotificationOptions } from 'notivue'

const defaultConfig: NotivueConfig = {
  pauseOnHover: true,
  pauseOnTouch: true,
  pauseOnTabChange: true,
  enqueue: false,
  avoidDuplicates: false,
  position: 'top-center', // 'top-left', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'
  teleportTo: 'body', // Or HTMLElement or `false` to disable
  limit: Infinity,
  animations: {
    enter: 'Notivue__enter',
    leave: 'Notivue__leave',
    clearAll: 'Notivue__clearAll'
  },
  transition: 'transform 0.35s cubic-bezier(0.5, 1, 0.25, 1)',
  notifications: defaultNotificationOptions
}

const defaultNotificationOptions: NotificationOptions = {
  success: {
    title: '', // Default title
    message: '', // Default message
    duration: 6000, // Duration of the notification
    ariaLive: 'polite', // Value of `aria-live` attribute
    ariaRole: 'status' // Value of `role` attribute
  }
  // ...
}

All default notification options

Type	title	message	duration	ariaLive	ariaRole
global	-	-	-	-	-
success	''	''	6000	polite	status
error	''	''	6000	assertive	alert
warning	''	''	6000	polite	alert
info	''	''	6000	polite	status
promise	''	''	Infinity	polite	status
promise-resolve	''	''	6000	polite	status
promise-reject	''	''	6000	assertive	alert

Push-scoped notification options

Notification options can be applied to a single notification by passing them to any push method:

push.success({
  title: '¡Éxito!',
  duration: 10000
})

Note

push methods only supports Notification Options and not top-level options like limit, enqueue, etc.