vue3-toastify

vue3-toastify is a highly customizable toast notification library for Vue 3. Key capabilities include:

• Customization: Easy setup, easy customization, and support for custom animations (e.g., animate.css).
• Display Control: Limit the number of simultaneous toasts, programmatic removal, and the ability to update existing toasts.
• Advanced Rendering: Display Vue 3 components inside toasts, support for RTL (Right-to-Left), and support for rendering dangerous HTML strings (disabled by default).
• Lifecycle & Interaction: onOpen and onClose hooks (with access to component props), and pausing toasts when the window loses focus.
• Visuals: Progress bars, dark mode support (including automatic system detection via html.dark), and colored themes.
• Logic: Promise support and per-toast behavior definitions.

If you do not provide a containerId, the library automatically assigns one based on the toast's position. For example, toasts with toast.POSITION.TOP_RIGHT will be grouped together, and toasts with toast.POSITION.BOTTOM_LEFT will be grouped in a different container.

// containerId defaults to `toast.POSITION.TOP_RIGHT`
toast('Wow so easy !');

// containerId defaults to `toast.POSITION.BOTTOM_LEFT`
toast('Wow so easy !', { position: toast.POSITION.BOTTOM_LEFT });

The expandCustomProps setting determines how the contentProps object is delivered to your custom component.

When expandCustomProps: true

Properties inside contentProps are spread directly onto the component. You can access them via standard defineProps.

<script setup>
// Accessing properties directly
const props = defineProps({
  title: String,
  color: String,
});
</script>

When expandCustomProps: false (Default)

All properties are wrapped in a single contentProps object prop.

<script setup>
import { PropType } from 'vue';

const props = defineProps({
  contentProps: {
    type: Object as PropType<{ title: string; color: string }>,
    default: () => ({}),
  },
});
</script>

The useHandler option is a callback function used to register global plugins or components within the toast's internal Vue application instance.

Since vue3-toastify maintains a separate application instance for rendering toasts, any global dependencies (like router or UI frameworks like Antd) required by toast content must be explicitly injected via this handler.

Signature: (instance: App<Element>) => void

To enable Right-to-Left (RTL) layout for all toasts across your entire application, pass the rtl: true option when installing the vue3-toastify plugin in your main Vue entry file. This configuration applies to the ToastContainerOptions.

import App from './App.vue';
import { createApp } from 'vue';
import Vue3Toasity from 'vue3-toastify';
import 'vue3-toastify/dist/index.css';

createApp(App).use(
  Vue3Toasity,
  {
    rtl: true,
  }, // global options type definition --> ToastContainerOptions
).mount('#app');

To ensure that only one toast is visible at a time (where each new toast overrides the previous one), set the multiple option to false in the global configuration when installing the plugin. This is useful for preventing toast stacking when you want to ensure only the most recent notification is shown.

import App from './App.vue';
import { createApp } from 'vue';
import Vue3Toasity from 'vue3-toastify';
import 'vue3-toastify/dist/index.css';

createApp(App).use(
  Vue3Toasity,
  {
    multiple: false,
  },
).mount('#app');

You can control how long it takes for the remaining toasts to collapse after one has exited by setting the collapseDuration property (in milliseconds) in your transition configuration. The default duration is 300ms.

<script setup lang="ts">
import { toast, Bounce, type CSSTransitionProps } from 'vue3-toastify';

const customAnimation: CSSTransitionProps = {
  ...Bounce,
  collapseDuration: 2000, // Duration in milliseconds
};

const notify = () => {
  toast('Wow so easy !', {
    transition: customAnimation,
    position: toast.POSITION.BOTTOM_RIGHT,
  });
};
</script>

By default, when you pass a custom Vue component to toast(), any extra properties provided in contentProps are nested under a single contentProps prop in your component.

To allow properties inside contentProps to be passed directly as top-level props to your component, set expandCustomProps: true.

Option 1: Enable globally

Set expandCustomProps: true in your application configuration when using the plugin.

Option 2: Enable per toast

Pass expandCustomProps: true within the options object of the toast() call.

// Global configuration
app.use(
  Vue3Toasity,
  {
    expandCustomProps: true,
  } as ToastContainerOptions,
);

// Per-toast configuration
toast(CustomComp, {
  type: 'warning',
  expandCustomProps: true,
  contentProps: {
    title: 'hello world',
    color: '#00a2ed',
  },
});

To apply a custom close button to all toasts throughout your application, provide the closeButton option when installing the Vue3Toasity plugin in your main application entry point.

import { createApp, h } from 'vue';
import Vue3Toasity from 'vue3-toastify';
import MyIcon from './MyIcon.vue';
import 'vue3-toastify/dist/index.css';

const app = createApp(App);

app.use(Vue3Toasity, {
  closeButton: (props) => h(MyIcon, props),
  autoClose: false,
  closeOnClick: false,
});

app.mount('#app');

By default, when a toast exits, the remaining toasts in the list collapse smoothly to fill the gap. You can disable this behavior by setting collapse: false within your transition configuration object. This is useful when you want the toast to disappear without triggering a layout shift in the remaining toasts.

<script setup lang="ts">
import { toast, Bounce, type CSSTransitionProps } from 'vue3-toastify';
import 'vue3-toastify/dist/index.css';

const customAnimation: CSSTransitionProps = {
  ...Bounce,
  collapse: false,
};

const notify = () => {
  toast('Wow so easy !', {
    transition: customAnimation,
    position: toast.POSITION.BOTTOM_RIGHT,
  });
};
</script>

If you cannot provide a static custom toastId, you can manually check if a specific toast is currently active by calling toast.isActive(id). This is useful when you want to capture the ID returned by the toast() function and use it for conditional logic.

<script setup lang="ts">
import { ref } from 'vue';
import { toast } from 'vue3-toastify';
import 'vue3-toastify/dist/index.css';

const toastId = ref('');

const notify = () => {
  if (!toast.isActive(toastId.value)) {
    // toast() returns the ID of the created toast
    toastId.value = toast('I cannot be duplicated!', {
      position: toast.POSITION.BOTTOM_CENTER,
    });
  }
};
</script>

<template>
  <div>
    <button @click="notify">Notify !</button>
  </div>
</template>