Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Toast
✓ import Toast from 'vue-toastification';
import 'vue-toastification/dist/index.css';
// In Vue 3 main.ts
createApp(App).use(Toast, { /* options */ });
// In Vue 2 main.js
Vue.use(Toast, { /* options */ });
✗ const Toast = require('vue-toastification'); // CommonJS import is not officially supported and can lead to issues, especially in Vue 3/ESM environments.
This is the default export for the plugin registration. Requires importing the CSS separately. Version 2.x is designed for Vue 3's `app.use`, while v1.x uses `Vue.use`.
useToast
✓ import { useToast } from 'vue-toastification';
// Inside a Vue 3 component setup() or <script setup>
const toast = useToast();
toast.success('Message');
✗ import useToast from 'vue-toastification'; // Not a default export.
const toast = require('vue-toastification').useToast; // CommonJS + named export issues.
import { useToast } from 'vue-toastification/composition/nuxt'; // Use this specific path ONLY when in Nuxt Composition API context, otherwise use the main package path.
Introduced in v2 for Vue 3's Composition API, providing a reactive interface to manage toasts from any component or outside. For Nuxt, a specific import path `vue-toastification/composition/nuxt` is often required for correct functionality.
POSITION
✓ import { POSITION } from 'vue-toastification';
// ... in plugin options
app.use(Toast, { position: POSITION.TOP_RIGHT });
✗ import POSITION from 'vue-toastification'; // Not a default export.
Named export for predefined toast positions. Often used in the global plugin options.
This quickstart demonstrates the setup of `vue-toastification` v2.x as a Vue 3 plugin and shows how to trigger different types of toasts, including custom component toasts, using the `useToast` Composition API hook.
import { createApp, h } from 'vue';
import App from './App.vue';
import Toast, { POSITION, TYPE } from 'vue-toastification';
import 'vue-toastification/dist/index.css';
const app = createApp(App);
app.use(Toast, {
position: POSITION.BOTTOM_RIGHT,
timeout: 3000,
closeOnClick: true,
pauseOnFocusLoss: true,
pauseOnHover: true,
draggable: true,
draggablePercent: 0.6,
showCloseButtonOnHover: false,
hideProgressBar: false,
closeButton: 'button',
icon: true,
rtl: false,
maxToasts: 5,
newestOnTop: true,
});
app.mount('#app');
// Inside your App.vue or any other component's <script setup>
// <template>
// <div>
// <button @click="showSuccessToast">Show Success</button>
// <button @click="showErrorToast">Show Error</button>
// <button @click="showCustomComponentToast">Show Custom Component Toast</button>
// </div>
// </template>
// <script setup lang="ts">
// import { useToast } from 'vue-toastification';
// const toast = useToast();
// const showSuccessToast = () => {
// toast.success('Your changes have been saved!');
// };
// const showErrorToast = () => {
// toast.error('An error occurred. Please try again.');
// };
// const showCustomComponentToast = () => {
// const CustomToast = h('div', { class: 'my-custom-toast' }, [
// h('h4', 'Custom Title'),
// h('p', 'This toast is rendered from a custom component!'),
// h('button', { onClick: () => toast.clear() }, 'Clear All Toasts')
// ]);
// toast(CustomToast, {
// type: TYPE.INFO,
// timeout: false, // Make it persistent
// closeButton: false,
// });
// };
// </script>
Debug
Known issues
breakingVue Toastification v2.x is a complete rewrite targeting Vue 3 exclusively. It is not compatible with Vue 2 applications. Attempting to use v1.x with Vue 3, or v2.x with Vue 2, will result in build errors or runtime failures.fixFor Vue 3 projects, install `vue-toastification@next` (or a specific v2.x release candidate) and follow its Vue 3-specific documentation for plugin registration (`app.use`) and Composition API usage (`useToast`). For Vue 2 projects, stick to `vue-toastification@^1.x`.
affects: >=2.0.0-rc.1, <1.x for Vue 3
breakingThe Sass division operator `/` is deprecated and will be removed in Dart Sass 2.0.0. If your project uses Sass and overrides `vue-toastification`'s SCSS variables (e.g., for custom themes), you might encounter deprecation warnings or build errors with newer Sass versions.fixReplace `/` with `math.div()` for division operations in your Sass code. Ensure you ` @use "sass:math";` at the top of your SCSS files. You might need to adjust variable overrides to accommodate these changes.
affects: >=1.7.12, >=2.0.0-rc.2
gotchaVue Toastification is primarily a client-side library and does not fully support Server-Side Rendering (SSR). Directly using `useToast` or global `$toast` instances during SSR can lead to `ReferenceError: HTMLElement is not defined` or `window is not defined` errors.fixWhen using with SSR frameworks like Nuxt, ensure that `vue-toastification` is loaded as a client-only plugin. In Nuxt 3, this often means creating a plugin with a `.client.ts` suffix or wrapping toast-related components in `<ClientOnly>` tags.
affects: >=1.0.0
gotchaIn Nuxt 3, directly importing `useToast` from `vue-toastification` may work in development but fail in production builds due to ESM/CommonJS compatibility issues, resulting in 'Named export 'useToast' not found' errors.fixFor Nuxt Composition API, specifically import `useToast` from `vue-toastification/composition/nuxt`. Alternatively, provide the toast instance via Nuxt's plugin system and inject it (e.g., `$toast`) in components. Ensure `vue-toastification` is transpiled in your `nuxt.config.js` if issues persist (`build.transpile: ['vue-toastification']`).
affects: >=2.0.0-rc.1 (Nuxt 3)
gotchaUsing version 1.7.14 with Vue 2.7.0+ might cause issues with the Composition API implementation, as Vue 2.7.0+ now includes its own Composition API. This can lead to conflicts or unexpected behavior if both are attempting to use different Composition API contexts.fixFor Vue 2.7.0+ projects, it is generally recommended to use the standard plugin registration (`Vue.use(Toast)`) and `this.$toast` interface, rather than trying to use `useToast` or other Composition API features from `vue-toastification` v1.x. For Composition API usage, migrating to `vue-toastification` v2.x (which requires Vue 3) is the recommended path.
affects: 1.7.14 (with Vue 2.7.0+)
Errors
Common errors & fixes
ReferenceError: HTMLElement is not defined
Attempting to use `vue-toastification` in an SSR environment (e.g., Nuxt) without proper client-side guarding.
fixEnsure `vue-toastification` is configured to run only on the client side. In Nuxt, register it as a client-only plugin (e.g., `~/plugins/toast.client.ts`) or wrap components using toasts in `<ClientOnly>`.
Named export 'useToast' not found
Incorrect import path for `useToast` in a Nuxt 3 project, or CommonJS module interop issues in ESM-only build environments.
fixFor Nuxt 3, import `useToast` specifically from `vue-toastification/composition/nuxt`. In other ESM environments, ensure your build tool correctly handles named exports from the library.
DEPRECATION WARNING: Using / for division outside of calc() is deprecated and will be removed in Dart Sass 2.0.0.
Your project's Sass configuration, or an older version of `vue-toastification`'s internal SCSS, uses the deprecated `/` operator for division.
fixUpdate your Sass files to use `math.div()` for division operations, ensuring ` @use "sass:math";` is present. If the warning comes from `vue-toastification`'s internals, ensure you are on a recent version that has addressed this (v1.7.12, v2.0.0-rc.2 fixed internal usages).
"default" is not exported by ".../node_modules/vue/dist/vue.runtime.esm-bundler.js", imported by ".../node_modules/vue-toastification/dist/esm/index.js".
Attempting to use `vue-toastification` v1.x in a Vue 3 project. `vue-toastification` v1.x expects a default export for Vue, which is not how Vue 3 bundles its ESM.
fixUpgrade to `vue-toastification` v2.x (e.g., `npm install vue-toastification@next`) if you are using Vue 3. Version 1.x is strictly for Vue 2.
Audit
Dependencies
vuerequiredRuntime peer dependency for all versions. v1.x requires Vue 2, v2.x requires Vue 3.