Vue Toastification

Common errors

• ReferenceError: HTMLElement is not defined

  cause Attempting to use `vue-toastification` in an SSR environment (e.g., Nuxt) without proper client-side guarding.
  fix Ensure `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

  cause Incorrect import path for `useToast` in a Nuxt 3 project, or CommonJS module interop issues in ESM-only build environments.
  fix For 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.

  cause Your project's Sass configuration, or an older version of `vue-toastification`'s internal SCSS, uses the deprecated `/` operator for division.
  fix Update 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".

  cause 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.
  fix Upgrade 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.

Warnings

• breaking Vue 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.
  Fix: For 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`.
• breaking The 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.
  Fix: Replace `/` 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.
• gotcha Vue 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.
  Fix: When 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.
• gotcha In 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.
  Fix: For 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']`).
• gotcha Using 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.
  Fix: For 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.

Install

• npm install vue-toastification npm
• yarn add vue-toastification yarn
• pnpm add vue-toastification pnpm

Imports

• Toast
  wrong:

  const Toast = require('vue-toastification'); // CommonJS import is not officially supported and can lead to issues, especially in Vue 3/ESM environments.

  correct:

  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 */ });

  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
  wrong:

  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.

  correct:

  import { useToast } from 'vue-toastification';
  // Inside a Vue 3 component setup() or <script setup>
  const toast = useToast();
  toast.success('Message');

  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
  wrong:

  import POSITION from 'vue-toastification'; // Not a default export.

  correct:

  import { POSITION } from 'vue-toastification';
  // ... in plugin options
  app.use(Toast, { position: POSITION.TOP_RIGHT });

  Named export for predefined toast positions. Often used in the global plugin options.

Quickstart

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>