vue-toastify v2.0.0-alpha.2

Vue Toastify

I wanted a notification plugin which I can use by passing props from the server and can also be called at run time. With this component it's has just become super easy. It's easily extendable and customizable and it has no dependencies.

Check it out at Netlify

Requires Vue 2.2.0+

• Vue Toastify
  • Quick start
  • Settings
    • Available settings
  • Status object
  • Available methods
    • Miscellaous methods
  • Customisation
    • Extending functionality
    • Extending styles
  • Usage
    • Basic
    • Vuex
  • Todos
  • Alternatives

Quick start:

npm i vue-toastify

or with CDNs:

• jsDeliver

• unpkg

  ---

In your main js file:

import VueToastify from "vue-toastify";
Vue.use(VueToastify);

Then anywhere just call:

this.$vToastify.success("easy-peasy");

Settings

You may pass a settings object to the use statement like so:

Vue.use(VueToastify, {
    my: "settings"
});

or change any of the settings during run-time with the following

this.$vToastify.setSettings(settingsObject);

This will return the current settings after the updates.

To use the vue router supported features pass in the router to the use statement as the 3rd argument like so:

import routerLoadedWithRoutes from "./router";

Vue.use(VueToastify, {}, routerLoadedWithRoutes);

Available settings

To fetch the current setting you may run the following which will return all the settings.

this.$vToastify.getSettings();

You may optionally pass an argument to the above to only get the value for that key.

Status

You can pass to the functions either a string for the body of the status and optionally a title for the second argument like so:

this.$vToastify.error("body", "title"); 

Or pass an object to the method:

this.$vToastify.info(stausObject);

The following properties can be set on the object:

You may additionally overwrite the following plugin settings on a notification by notification basis by adding them on the status object.

• canTimeout
• canPause
• defaultTitle
• duration - The time the notification is displayed for in milliseconds regardless of its type. (this cannot be updated later)
• theme
• hideProgressbar
• transition
• iconEnabled
• draggable
• dragThreshold
• orderLatest

You may alternatively pass in an http error response like:

fetch().then().catch(error => this.$vToastify.error(error));

Only this.$vToastify.error() will look for status and statusText on the error object.

Every notification method returns a unique id associated to your notification object.

Additional methods

The notification supports multiple modes

You can either pass the mode property on the status object which is one of the following strings: "prompt", "loader" or by calling:

this.$vToastify.loader("Please Wait...")

this.$vToastify.prompt({
    body: "Are there hot singles in your area?",
    answers: { Yes: true, No: false }
})

The prompt does not return an id instead it returns a Promise so may use it as:

...}).then(value => {
    if (value) {
        this.$vToastify.prompt("Is it a scam?")
            .then(value => console.log(value ? "Yay!" : "Nay"))
    }
})

The answers object consist of a key value pairs in the object where the key is displayed to the user and the value returned by the promise. If not set it defaults to: { Yes: true, No: false }.

There are various events are emitted by the notification:

• vtFinished
• vtDismissed
• vtStarted
• vtPaused
• vtResumed
• vtDragStarted
• vtBeingDragged

• vtDragFinished

  to which you can listen by either the listen or the listenOnce method. The event's payload is an object containing the notification's id:

this.$vToastify.listen("vtDismissed", payload => console.log(payload.id))

The drag events will also include a property called position which is an object of { x: Integer, y: Integer } where x is left and y is top offset in pixels from the client view port.

Miscellaous methods:

A loader cannot be dismissed, you'll have to stop the loader yourself like so:

this.$vToastify.stopLoader(id)

This will stops the loader with the given id or loaders if array of ids given. If no id provided, all loaders will be closed. It will return the count of the loaders stopped.

For returning a notification object use:

this.$vToastify.getToast(id)

This if found returns the notification object from the visible ones or queued toasts otherwise all of the notification objects in an array from both the visible and queued toasts. If not found returns false.

For updating the notification object during run-time use:

this.$vToastify.changeToast(id, statusObject)

This will merge the object you pass in and the existing notification. It will return true if successfully updated and false if the notification isn't found.

For removing a notification use:

this.$vToastify.removeToast(id)

This will remove the notification if the id is given otherwise it will remove all of the notifications. If id supplied and not found between the queued or currently displaying notifications, it will return false, otherwise it returns the ids of the currently visible notifications.

To pass a notification from the server, assign your notification object to window.notification before importing your scripts. On mount this will gets displayed to the user. If this notification object has a property called delay, the notification display will be delayed by the given number of milliseconds.

Customisation

Extending the functionality

You can add your own methods to the plugin like so:

Vue.use(VueToastify, {
  customNotifications: {
    clientError: {
      body: "You did it!",
      defaultTitle: false,
      icon: '<svg width="50" height="50">\n' +
              '<rect width="50" height="50" style="fill:rgb(0,0,255);" />\n' +
            '</svg> ',
      canTimeout: false
    },
    moreOfTheAbove: { ...
  }
});

If the above is defined in the customNotifications object, you can use this method like so:

this.$vToastify.clientError("this will overwrite the body", "this will add a title");

or as usual pass in an object which will merge with the predefined props.

Extending the styles

Default styles maybe overridden with !important. To add custom styles you all you have to do is follow the example in ./src/assets/toast.scss and add your custom styles. Once added rename .vt-theme-dark to .vt-theme-my-custom-name and in the settings or the status object pass the theme as theme: "my-custom-name". Include this stylesheet in the project and you're good to go.

Usage

Basic usage

In your main js file:

import VueToastify from "vue-toastify";

Vue.use(VueToastify);

Then anywhere just call:

this.$vToastify.info("Easy as that");

Vuex usage

import Vue from "vue";

const mutations = {
  updateValue(state, value) {
    state.value = value;
    Vue.$vToastify.success("Successfully updated value!");
    // OR
    this._vm.$vToastify.success("Successfully updated value!")
  }
};

JSX usage

// In your vue component's methods:
runToast(){
  // This is needed to avoid using the global `h` function, which vue complains about.
  // You'll also need `lang="jsx"` in your script tag.
  const h = this.$createElement;
  this.$vToastify.success({
    body: h("div", {}, [
      h("h1", {}, "Hello"),
      h("p", {}, "World")
    ])
  });
  // OR
  const h = this.$createElement;
  this.$vToastify.success({
    body: <div>
      <h1>Hello</h1>
      <p>World</p>
    </div>
  });
  // OR With Vue 2.7
  // Your mileage with this may vary - you might need to import `h` from vue
  this.$vToastify.success(()=><div>Hello</div>)
}

You can also pass in a function for the body which will have h as an argument to circumvent the global h function.

Vue.$vToastify.success({
  body: h => h("div", {}, "hello")
});
// OR
Vue.$vToastify.success({
  body: (h) => <div>hello</div>
});
// OR as only a function
Vue.$vToastify.success((h)=><div>hello</div>);

Todos

• Add ability to display notifications simultaneously at different locations

• Create docs site

• Accept components as content or as icon

• Get url props on the answers object for redirecting on click of the button

V2

• Clean up icons

• Set styles as an external stylesheet

• setSettings to return boolean.

• url to only accept an object

• Rewrite in Typescript (+ status object to be a class)

• Build as TDD

Alternatives

Packages with similar capabilities:

• Vue Snotify

• vue-toastification