Module Configuration

Configure Nuxt Notify globally in your nuxt.config.ts to set default behavior for all toasts.

Configuration

Add the notify key to your Nuxt config:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["nuxt-notify"],

  notify: {
    position: "top-right",
    duration: 5000,
    maxToasts: 5,
    theme: "light",
    showIcon: true,
    showProgress: false,
  },
});

Configuration Options

`position`

Default position for all toasts.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    position: "bottom-right",
  },
});

Can be overridden: Each toast can specify its own position using the position option.

`duration`

Type: number
Default: 5000

Default duration in milliseconds for all toasts.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    duration: 7000, // 7 seconds
  },
});

Common values:

Quick messages: 3000 (3 seconds)
Standard: 5000 (5 seconds)
Important: 10000 (10 seconds)
Persistent: Infinity (never auto-dismiss) ::

`maxToasts`

Type: number
Default: 5

Maximum number of toasts visible at once. When this limit is reached, the oldest toast is removed when a new one appears.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    maxToasts: 3, // Only show 3 toasts at a time
  },
});

Setting this too high may clutter the UI. A value between 3-5 is recommended for most applications.

`theme`

Type: 'light' | 'dark' | 'system'
Default: 'light'

Default color theme for toasts.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    theme: "dark",
  },
});

Theme Options:

light: Light theme with dark text
dark: Dark theme with light text
system: Automatically matches user's system preference

`showIcon`

Type: boolean
Default: true

Whether to show icons in toasts by default.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    showIcon: false, // Disable icons globally
  },
});

When showIcon is true, you must have @nuxt/icon installed. If set to false, the icon module is optional.

`showProgress`

Type: boolean
Default: false

Whether to show progress bars on toasts by default.

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    showProgress: true, // Show progress bars on all toasts
  },
});

Complete Configuration Example

Here's a complete configuration with all options:

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["@nuxtjs/tailwindcss", "@nuxt/icon", "nuxt-notify"],

  notify: {
    // Position
    position: "top-right",

    // Timing
    duration: 5000,

    // Stack size
    maxToasts: 5,

    // Appearance
    theme: "dark",
    showIcon: true,
    showProgress: false,
  },
});

Overriding Global Config

All global configuration options can be overridden per toast:

example.vue

<script setup>
const toast = useToast();

// Uses global config
toast.success("Uses defaults");

// Overrides global config
toast.success("Custom", "Overriding duration and position", {
  duration: 10000,
  position: "bottom-center",
  showProgress: true,
});
</script>

Configuration by Environment

You can set different configurations for different environments:

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    // Production settings
    position: "top-right",
    duration: 5000,

    // Override for development
    ...(process.env.NODE_ENV === "development" && {
      duration: 10000, // Longer duration in dev
      showProgress: true,
    }),
  },
});

Theme Configuration

Light Theme

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    theme: "light",
  },
});

Best for applications with predominantly light color schemes.

Dark Theme

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    theme: "dark",
  },
});

Best for applications with dark interfaces or when targeting users who prefer dark mode.

System Theme

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    theme: "system",
  },
});

Automatically adapts to the user's system preference (light/dark mode). This is the most user-friendly option as it respects user preferences.

Recommended: Use theme: 'system' to provide the best experience for all users, regardless of their preference.

Tailwind v4 Dark Mode

If you're using Tailwind v4 and experiencing dark mode issues, add this to your CSS:

assets/css/main.css

@import "tailwindcss";
@import "nuxt-notify/styles";

/* Ensure Tailwind v4 dark utilities work with html.dark */
@custom-variant dark (&:where(.dark, .dark *));

TypeScript Support

Nuxt Notify is fully typed. Your configuration will have full autocomplete and type checking:

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    position: "top-right", // ✅ Autocomplete available
    duration: 5000, // ✅ Type checked as number
    theme: "system", // ✅ Only valid values allowed
  },
});

Validation

Invalid configuration values will be caught during build:

nuxt.config.ts

export default defineNuxtConfig({
  notify: {
    position: "invalid", // ❌ Build error: Invalid position
    duration: "5000", // ❌ Build error: Must be number
    theme: "blue", // ❌ Build error: Invalid theme
  },
});

Best Practices

Position

Top positions: Better for critical notifications that need immediate attention
Bottom positions: Less intrusive, good for background processes
Center positions: Best for important announcements

Duration

Short (2-3s): Simple confirmations
Medium (5-7s): Standard notifications with descriptions
Long (10s+): Important messages with actions
Infinite: Messages requiring user action

Max Toasts

3-5: Recommended for most apps
1: For critical notifications only
10+: May overwhelm users

Theme

Use system for best user experience
Match your app's theme if you have a fixed color scheme

Tip: Start with the defaults and adjust based on user feedback and your app's specific needs.