DOCSEARCHbyAlgolia
Submit Docs

Notivue Documentation

repository·main·Indexed 21 days ago

https://github.com/smastrom/notivue

A modular toast notification system for Vue and Nuxt applications. Notivue provides both ready-made components and a headless API for full UI customization. It includes a built-in Nuxt module, a comprehensive Push API for standard and promise-based notifications, and reactive composables like useNotivue and useNotifications to manage global configuration and notification states.

Tokens
7K
Snippets
27
Records
34
Agent score
75%

What's inside Notivue

  1. How headless Notivue works with custom components

    main

    Notivue provides a headless API, meaning you can use your own custom UI components instead of the built-in <Notification />.

    When using <Notivue v-slot="item">, the item object provides the necessary data for accessibility and interaction:

    • item.message: The notification text.
    • item.ariaRole: The appropriate ARIA role.
    • item.ariaLive: The ARIA live property.
    • item.clear: A function to dismiss the notification.
    <script setup>
import { Notivue, push } from 'notivue'
</script>

<template>
  <button @click="push.success('Hi! I am your first notification!')">Push</button>

  <Notivue v-slot="item">
    <!-- Your custom notification component -->
    <div class="rounded-full flex py-2 pl-3 bg-slate-700 text-slate-50 text-sm">
      <p :role="item.ariaRole" :aria-live="item.ariaLive" aria-atomic="true">
        {{ item.message }}
      </p>

      <button
        @click="item.clear"
        aria-label="Dismiss"
        class="pl-3 pr-2 hover:text-red-300 transition-colors"
        tabindex="-1"
      >
        <!-- Icon here -->
      </button>
    </div>
  </Notivue>
</template>

  2. Setup Notivue in a Vite/Vue project

    main

    To use Notivue in a standard Vue application (e.g., via Vite), you need to initialize it in your main entry point and include the necessary CSS files.

    If you use the built-in <Notification /> component, you must import notivue/notification.css. If you want the default animations, import notivue/animations.css.

    import { createApp } from 'vue'
import { createNotivue } from 'notivue'

import App from './App.vue'

import 'notivue/notification.css' // Only needed if using built-in <Notification />
import 'notivue/animations.css' // Only needed if using default animations

const notivue = createNotivue(/* Options */)
const app = createApp(App)

app.use(notivue)
app.mount('#app')

  3. Setup Notivue in Nuxt

    main

    Notivue provides a built-in Nuxt module. To set it up, add 'notivue/nuxt' to your modules array in nuxt.config.ts. You should also include the CSS files in the css array if you plan to use the built-in components.

    // nuxt.config.ts
export default defineNuxtConfig({
  modules: ['notivue/nuxt'],
  css: [
    'notivue/notification.css', // Only needed if using built-in <Notification />
    'notivue/animations.css' // Only needed if using default animations
  ],
  notivue: {
    // Options
  }
})

  5. Use Notivue functions and components in Nuxt

    main

    The Notivue Nuxt module automatically provides auto-imports for all Notivue functions, objects, and components. You can use them directly in your .vue files or composables without manual imports.

    • Functions/Objects: Automatically imported from notivue.
    • Components: Automatically registered as Nuxt components.

  7. Use built-in Notivue components

    main

    In your Vue templates, use the <Notivue> component as a container. It provides a v-slot="item" which gives you access to the individual notification data. You can then pass this item to the built-in <Notification /> component.

    <script setup>
import { Notivue, Notification, push } from 'notivue'
</script>

<template>
  <button @click="push.success('Hi! I am your first notification!')">Push</button>

  <Notivue v-slot="item">
    <Notification :item="item" />
  </Notivue>
</template>

  8. Configure Notivue via NotivueConfig

    main

    The NotivueConfig interface defines the global behavior of the notification system. You can use it to set the position, limits, animations, and default options for different notification types.

    Key Configuration Options:

    • position: Sets the screen placement. Options: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'.
    • limit: Maximum number of notifications to display simultaneously. Defaults to Infinity.
    • enqueue: If true, notifications exceeding the limit are added to a queue.
    • avoidDuplicates: If true, prevents duplicate notifications from appearing (it will instead update the duration of the existing one).
    • pauseOnHover, pauseOnTouch, pauseOnTabChange: Boolean flags to pause notification timers during user interaction.
    • notifications: A mapping of NotificationType (e.g., 'success', 'error', 'info', 'warning', 'promise') or 'global' to specific NotificationOptions.
    • animations: Defines CSS classes for enter, leave, and clearAll transitions.
    • transition: A CSS transition string (e.g., transform 0.35s cubic-bezier(...)) applied when notifications reposition themselves.
    • teleportTo: A selector, HTMLElement, or false to determine where the notification stream is rendered.
    const config: NotivueConfig = {
  position: 'top-right',
  limit: 5,
  enqueue: true,
  pauseOnHover: true,
  notifications: {
    success: { duration: 3000 },
    error: { duration: 5000 }
  }
};

  9. Configure the global Notivue settings

    main

    The DEFAULT_CONFIG object defines the global behavior of the notification system. You can override these values during setup to control positioning, queuing, and animations.

    Key configuration options include:

    • position: The screen position (e.g., 'top-center').
    • pauseOnHover, pauseOnTouch, pauseOnTabChange: Boolean flags to pause notifications during user interaction.
    • enqueue: Whether to queue notifications instead of showing them all at once.
    • limit: Maximum number of notifications to show simultaneously.
    • teleportTo: The DOM element to which notifications are teleported (defaults to 'body').
    • avoidDuplicates: Whether to prevent showing identical notifications.
    • transition: The CSS transition string used for animations.
    • animations: Object containing CSS class names for enter, leave, and clearAll states, prefixed with Notivue__.
    export const DEFAULT_CONFIG: NotivueConfigRequired = {
   pauseOnHover: true,
   pauseOnTouch: true,
   pauseOnTabChange: true,
   enqueue: false,
   position: 'top-center',
   teleportTo: 'body',
   notifications: DEFAULT_NOTIFICATION_OPTIONS,
   limit: Infinity,
   avoidDuplicates: false,
   transition: 'transform 0.35s cubic-bezier(0.5, 1, 0.25, 1)',
   animations: {
      enter: 'Notivue__enter',
      leave: 'Notivue__leave',
      clearAll: 'Notivue__clearAll',
   },
}

  10. Configure Notivue in Nuxt

    main

    Notivue can be configured via the notivue key in your nuxt.config.ts. These options are made available in your application via useRuntimeConfig().public.notivue.

    By default, the module automatically adds a client-side plugin to initialize Notivue. If you wish to prevent the automatic plugin injection, set addPlugin: false in your configuration.

    export default defineNuxtConfig({
  modules: ['notivue'],
  notivue: {
    // Your Notivue options here
    addPlugin: true // Set to false to disable automatic plugin injection
  }
})

  11. Configure NotivueSwipeProps

    main

    The NotivueSwipeProps interface defines the configuration options for the NotivueSwipe extension. This allows you to control how swipe gestures interact with notifications, including threshold sensitivity, element exclusion, and device-specific behavior.

    Options

    PropTypeDefaultDescription
    itemNotivueItemRequiredThe notification item exposed by Notivue.
    touchOnlybooleanundefinedIf true, the clear-on-swipe behavior is only enabled for touch interactions.
    excludestring`

  12. Use NotivueKeyboardSlot for custom notification elements

    main

    When using the NotivueKeyboard slot, you receive props that allow you to manage focusability for accessibility. You must apply these values to your custom notification elements to ensure they are part of the keyboard navigation stream.

    • Use elementsTabIndex (a TabIndexValue of 0 | -1) on individual focusable elements within a notification via :tabindex="elementsTabIndex".
    • Use containersTabIndex (a ContainersTabIndexMap) to manage the tabindex of the notification containers themselves. This should be passed to the main Notivue component via the :containersTabIndex prop.
    <template>
  <NotivueKeyboard>
    <template #default="{ elementsTabIndex, containersTabIndex }">
      <!-- Apply containersTabIndex to the Notivue component via props -->
      <!-- Apply elementsTabIndex to focusable elements inside the notification -->
      <div class="notification">
        <button :tabindex="elementsTabIndex">Action</button>
      </div>
    </template>
  </NotivueKeyboard>
</template>