vue-on-toast

vue-on-toast

vue-on-toast An SSR-enabled, flexible, fully featured, bootstrap-themed toast notification library for Vue.

vue-on-toast focuses on performance and size with the JavaScript weighing in at 6.37kb (2.25kb gzipped) and the CSS at 10.37kb.

Demo

A simple demo can be found at this plunker.

Getting Started

In keeping with Vue's progressive design philosophy, you can drop vue-on-toast onto an existing page or you can add it to a build system. Choose one of the approaches below based on your needs.

CDN Installation

If you are using Vue in a new or existing application without a build system and you would like to use vue-on-toast, you can add it from CDN and it will install itself automatically.

<link href="https://unpkg.com/vue-on-toast/dist/vue-on-toast.min.css" rel="stylesheet" type="text/css">
 
<script src="https://unpkg.com/vue/dist/vue.js"></script>
 
<script src="https://unpkg.com/vue-on-toast/dist/vue-on-toast.min.js"></script>

NPM Install

npm install vue-on-toast

In the root of your application, import and install vue-on-toast.

import Vue from 'vue'
import VueOnToast from 'vue-on-toast'
 
Vue.use(VueOnToast)

Import CSS or Stylus

@import 'node_modules/vue-on-toast/dist/vue-on-toast.styl'

or

@import 'node_modules/vue-on-toast/dist/vue-on-toast.css'

NOTE: Using the vue-on-toast css is not required. Although lightweight at 10.41kb minified, you can provide your own CSS to either further shrink the library size or to provide different functionality and feel.

Add Toast Container

vue-on-toast supports multiple toast containers, each allowing a unique configuration (see the Toast Config Options section).

At least one toast container component must be included in your application, preferably outside of your router.

<toast-container></toast-container>

Adding and Removing Toasts

Popping a toast in a component

Vue.use(VueOnToast) will add a $vueOnToast instance to the Vue prototype, exposing pop() and remove() methods.

Within your component, you can call this.$vueOnToast.pop(). The pop method takes accepts two different forms of parameters: inline parameters for type, title and body, and an object that allows for additional configuration.

this.$vueOnToast.pop('success', 'Toast Title', 'Popped from Vue instance')

OR

let toast = {}
this.$vueOnToast.pop(toast)

The following properties are exposed on the toast instance via the object parameter syntax and will override container-level configurations (see the Toast Config Options section).

Property	Type	Default	Description
toastId	string	Automatically generated UUID	UUID specific to the toast instance. Cannot be overridden and is guaranteed to be unique across all containers. It is populated on the toast.
toastContainerId	int	null	A numeric value that matches the target container to pop the toast on. If it is omitted, the toast will be popped on all available containers.
type	string	none	If a type is not specified and the toast is added via the pop function, an error will be thrown. Options are: success, error, info, wait, warning.
title	string	null	The title of the toast.
body	string	null	The body of the toast.
bodyOutputType	string	null	By default, the body will be rendered as a raw string. To render HTML, 'TrustedHtml' should be passed via this parameter. To render a component, 'Component' should be passed via this parameter and the body parameter should contain the name of the component to render.
onShowCallback	function	null	An optional function to invoke after the toast has been added to the target container. The toast instance will be passed to the provided function as the only parameter.
onHideCallback	function	null	An optional function to invoke after the toast has been removed from the target container. The toast instance will be passed to the provided function as the only parameter.
showCloseButton	boolean	Inherited from config (false)	Determines if the close button should be shown on the toast.
toastHtml	string	Inherited from config (×)	The HTML string that should be rendered if showCloseButton is true.
clickHandler	function	null	An optional function that returns true/false. If provided and if toastConfig.tapToDismiss is true OR the toast close button was clicked, this function will be invoked, passing the toast instance and the isCloseButton flag (indicating if the click originated from the close button). If the function returns true, the toast will be dismissed, else the toast will persist.
timeout	number	Inherited from config	The number of milliseconds to show the toast before it should be automatically dismissed. If set to 0, the toast will be considered "sticky" and will not automatically self-dismiss.

Popping a toast outside of a Vue instance

If you need to pop a toast outside of a Vue instance (such as a Vuex store module), you can import the VueOnToast instance and access the ToastService directly:

import VueOnToast from 'vue-on-toast'

VueOnToast.ToastService.pop('info', 'Toast Title', 'Popped from service directly')

Remove Existing Toast

A remove function is exposed that accepts two optional parameters: toastId and toastContainerId.

These parameters can be used to clear toasts by specific id, by container id, by both, or by neither. If both parameters are omitted, all toasts in all containers will be removed.

Remove from inside Vue Instance

let toast = this.$vueOnToast.pop('success', 'title', 'body')
this.$vueOnToast.remove(toast.toastId, toast.toastContainerId)

Remove from outside Vue Instance

import VueOnToast from 'vue-on-toast'

let toast = VueOnToast.ToastService.pop('info', 'title', 'body')
VueOnToast.ToastService.remove(toast.toastId, toast.toastContainerId)

Toast Config Options

Each individual toast-container component instance offers a considerable degree of customization and flexibility via the toastConfig property.

<toast-container :toastConfig="customConfig"></toast-container>

export default {
    computed: {
        customConfig: function () {
            return { toastContainerId: 1 }
        }
    }
}

The following properties are exposed to the container via the toastConfig property:

Property	Type	Default	Description
animation	string	"fade"	There are three different built-in transition effects that can be applied to a container: "fade", "ease-out-left", and "ease-out-right". Custom transitions can be created as well and should be passed to this parameter.
bodyClass	string	"vot-body"	The class that is applied to the div that holds the body of the toast where the body parameter is applied.
closeHtml	string	×	The html that should be rendered if showCloseButton is true. This property is automatically inherited by toasts.
defaultTypeClass	string	"vot-info"	Fallback toast type when the toast is added to the container.
typeClasses	object	See Description	An object mapping each toast type to its css class. The following are the default options: error: "vot-error" info: "vot-info" wait: "vot-wait" success: "vot-success" warning: "vot-warning"
iconClasses	object	See Description	An object mapping each icon per toast type to its css class. The following are the default options: error: "vot-icon-error" info: "vot-icon-info" wait: "vot-icon-wait" success: "vot-icon-success" warning: "vot-icon-warning"
mouseoverTimerStop	boolean	false	If true, the dismiss timer is paused while the toast is moused over.
newestOnTop	boolean	true	If true, the toast is pushed to the top of the container list. If false, the toast is added to the bottom of the container list.
positionClass	string	"vot-top-right"	The container can be positioned in nine distinct positions provided by the library, and can be further customized via this parameter. "vot-top-full-width", "vot-bottom-full-width", "vot-top-left", "vot-top-center", "vot-top-right", "vot-bottom-left", "vot-bottom-center", "vot-bottom-right", "vot-center"
preventDuplicates	boolean	false	If true, the toast id is checked against all other toasts currently displayed by the container. If there is no match, the body is compared to the bodies of all toasts currently displayed by the container. If there is a match, the new toast is not added.
tapToDismiss	boolean	true	If true, tapping (or clicking) the toast will automatically dismiss it. If false, taps (or clicks) have no effect on the toast.
timeout	number OR object	5000	By default, toasts have a timeout setting of 5000, meaning that they are removed after 5000 milliseconds. If the timeout is set to anything other than a number greater than 0, the toast will be considered "sticky" and will not automatically dismiss. The timeout can be configured either globally for all toast types as a number, or per toast type as an object (timeout: {error: 1000}}).
titleClass	string	"vot-title"	The class that is applied to the div that holds the title of the toast where the title parameter is applied.
toastContainerId	number	null	A unique identifier to enable container-specific adds and removals.
showCloseButton	boolean OR object	false	By default, the close button is not shown for any toast type. This can be overridden for all toast types by providing false, or it can be overridden per toast type as an object (showCloseButton: {error: true}}).

Author

Stabzs

Copyright

Copyright © 2017 Stabzs.

Licence

This project is licensed under the MIT license. See the LICENSE file for more info.