Vue Toastification (for Vue 2)

Are you using Vue 3? Check out Vue Toastification v2!

Light, easy and beautiful toasts!

Wanna try it out? Check out the live demo!

• Vue Toastification (for Vue 2)
• Features
• Demo
• Installation
• Usage
  • Plugin registration
  • Nuxt registration
  • Nuxt and Composition API
  • Injecting the Toast CSS
  • Composition API registration
  • Generic registration
  • Positioning the Toast
  • Toast types
  • Setting the toast timeout
  • Using a custom component
  • Render a component
  • Close the toast using a custom component
  • Render a JSX component
  • Render a component with props and events
  • Dismiss toasts programmatically
  • Update toasts programmatically
  • Clear all toasts
  • Styling
  • Custom toast classes
  • Custom toast container classes
  • Override SCSS variables
  • Right to left support
  • Transitions
  • Custom transitions
  • Named transitions
  • Transition classes
  • Transition durations
  • Toast Icons
  • Disabling icons
  • Using custom icons
  • Close Button
  • Hiding the close button
  • Only show the close button on hover
  • Custom close button component
  • Custom close button classes
  • Presetting default toast options per type
  • Updating default options
  • Custom toast filters
  • filterBeforeCreate
  • filterToasts
  • Custom toast containers
  • Existing nodes as toast containers
  • Async nodes as toast containers
• API
  • Plugin registration (Vue.use)
  • Toast (this.$toast)
  • Toast Content Object
  • Toast Options Object
• Acknowledgements
• License

Features

• Built-in Nuxt support
• Support for the new Composition API and Vue 3
• Generic registration allows it to be used inside any app, even React!
• Fully written in Typescript with full types support
• RTL support
• Easy to set up for real, you can make it work in less than 10sec!
• Customize everything
• Swipe to close 👌
• Use your custom components or JSX as the toast body for endless possibilities!
• Create custom experiences with onClose, onClick, and onMounted hooks
• Custom toast filtering and enqueueing with lifecycle hooks
• Remove toasts programmatically
• Update toasts programmatically
• Define behavior per toast
• Pause toast when hovering and when the window loses focus 👁
• Fancy progress bar to display the remaining time
• Use your themes and animations easily
• And much more!

Demo

Need some more convincing? Check out the demo

You can also check some examples.

Installation

$ yarn add vue-toastification
$ npm install --save vue-toastification

Using Vue 3? You should install Vue Toastification v2 instead.

Usage

Plugin registration

Add it as a Vue plugin:

import Vue from "vue";
import Toast from "vue-toastification";
// Import the CSS or use your own!
import "vue-toastification/dist/index.css";

const options = {
    // You can set your default options here
};


Vue.use(Toast, options);

And then just call it in your components with

this.$toast("I'm a toast!");

// Or with options
this.$toast("My toast content", {
    timeout: 2000
});
// These options will override the options defined in the "Vue.use" plugin registration for this specific toast

Or reference in your Vuex store with

this._vm.$toast("I'm a toast!");

// Or with import
import Vue from "vue";

Vue.$toast("My toast content", {
    timeout: 2000
});

Nuxt registration

Vue Toastification comes with full Nuxt and Nuxt Typescript support.

Note: As a client library, Vue Toastification does not support SSR, so the object $toast will not be available on the server, only on the client.

To use it, register it as a Nuxt module:

// nuxt.config.js

export default {
  // ...
  modules: [
    // With default plugin options
    "vue-toastification/nuxt",

    // You can also pass plugin options
    ["vue-toastification/nuxt", {
      timeout: 1000,
      draggable: false
    }]
  ],

  // Or pass options through the "toast" key
  toast: {
    timeout: 2000,
    closeOnClick: false
  }
  // ...
}

If you are using Typescript with Nuxt, you may need to add "vue-toastification/nuxt" to your external types list to fully load them. e.g.:

// tsconfig.json

{
  "compilerOptions": {
    "types": [
      "vue-toastification/nuxt"
    ]
  }
}

Nuxt and Composition API

Since Vue Toastification is auto installed with nuxt, we need not provide it a second time.

To access your $toast instance from within setup(), import from vue-toastification/composition/nuxt like so:

// MyComponent.vue

// Import from vue-toastification/composition/nuxt, not vue-toastification/composition
import { useToast } from "vue-toastification/composition/nuxt";

// Then, in the setup method
  setup() {
    const toast = useToast()
    // Use it like you would use this.$toast
  }

Injecting the Toast CSS

By default, when you register the module within Nuxt it automatically injects the CSS required to display the toasts using the default vue-toastification/dist/index.css file.

If you have your own CSS file, you can instruct the module to inject it instead by providing its absolute path through the cssFile option. You can also disable CSS injection by setting cssFile: false:

// nuxt.config.js

export default {
  // ...
  modules: [
    "vue-toastification/nuxt",
  ],

  toast: {
    // Use your own CSS file
    cssFile: "path/to/your/file.scss",
    // Or disable CSS injection
    cssFile: false
  }
  // ...
}

If your CSS file is actually an SCSS or SASS file, just make sure that you have the correct loaders installed. See Nuxt docs on that.

If you set cssFile: false it's important to notice that timeout won't work. See #107.

Composition API registration

Vue Toastification comes with built-in support for the Composition API. It is fully optional and won't interfere with your usage if you do not use composition.

Composable plugins are a little different than regular Vue plugins as they rely on providers and injectors to work without access to the this keyword. Vue Toastification exposes two new functions to make that possible: provideToast and useToast.

Play with a live example here:

To access toasts inside setup, you first need to register the provider. To make the toasts available from anywhere within your application, set up the provider on the root component of your app:

// App.vue

// Import from vue-toastification/composition, not vue-toastification
import { provideToast } from "vue-toastification/composition";
// Also import the toast's css
import "vue-toastification/dist/index.css";

// Then, on the setup method
  setup() {
    // Pass the Plugin Options here
    provideToast({ timeout: 3000 });
    // This is similar to `Vue.use(Toast)`, but will not register `$toast` to the Vue instance.
  }

Then get access to the toast interface on your components with useToast:

// MyComponent.vue

import { useToast } from "vue-toastification/composition";
// ...

  setup() {
    // Same interface as this.$toast
    const toast = useToast();

    const showToast = () => toast.success("I'm a toast!");
    const clearToasts = () => toast.clear();
    return { showToast, clearToasts };
  }

Each call to provideToast will generate an independent version of the plugin available to its descendants through useToast. This means that if you call provideToast in multiple locations, each one will mount an independent toast container. useToast will always return the toast interface of the closest provideToast call in its parent component tree.

The toast interface returned by useToast can, however, point to an arbitrary plugin instance if you provide an eventBus to it. Event buses are Vue instances used to carry events between the interface and the plugin. They are automatically generated for you, but you can also specify your own when calling Vue.use(Toast) or provideToast():

// Create a new event bus
const eventBus = new Vue();

// Pass it to provideToast as a plugin option
provideToast({ eventBus });
// Or register with Vue.use
Vue.use(Toast, { eventBus });

// Get the interface of the closes parent plugin instance
const toast = useToast();
// Get the interface of an arbitrary plugin instance
const toast = useToast(eventBus);

Generic registration

Vue Toastification allows you to register it as a generic interface not bound to Vue as a plugin. That may be useful if you are using it in an app not written in Vue.

It still depends on Vue as a framework, but not on the root vue instance of your page.

Play with a live React.js demo here:

To register it, use the createToastInterface helper:

import { createToastInterface } from "vue-toastification";

const pluginOptions = {
  timeout: 4000
};

// Create the interface
const toast = createToastInterface(pluginOptions);

// Use it
toast.success("Standalone toasts!");

When you call createToastInterface, it will automatically mount the toast container and sets everything for you. It returns a toast interface and you can use it as you would with this.$toast.

createToastInterface may take a second, optional, Vue instance parameter. Use it to specify an optional parent Vue instance to the interface.

You can also create just the toast interface without mounting the plugin by passing just an event bus instance to createToastInterface. Event buses are simple Vue instances used to pass events around the plugin. They are created automatically, but you can specify your own if you need to get access to the interface elsewhere.

// Create a new event bus
const eventBus = new Vue();

// Mount plugin and return an interface
const toast1 = createToastInterface({ eventBus });

// Later retrieve a copy of that interface without mounting the plugin again
const toast2 = createToastInterface(eventBus);

// Note that on the second call just the eventBus was passed, not as an object but as
// a reference to the bus.

Positioning the Toast

By default, the toasts wi