vue-notifications
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    Codacy Badge Build Status GitHub license Known Vulnerabilities NPM Package Quality

    | SITE | DOCS | EXAMPLES | GITHUB | LICENSE |

    vue-notifications

    VueNotifications - agnostic library for non-blocking notifications.


    Introduction and WTF is it?

    vue-notifications is "Vue.js agnostic non-blocking notifications library"... and it's a lie )) Seriously.

    vue-notificationsit's basically a bridge between your actual app and UI-notfications libs, like mini-toastr.

    Why do we need this?

    Because we want to have a way to show notifications and a way to easy replace UI library that show them without rewrite the code.

    What vue-notifications actually do?

    It's allow you to declare your notifications in blocks like this one:

    export default {
        name: 'DemoView',
        data () {
          //...
        },
        methods: {
          //...
        },
        notifications: {
          showLoginError: { // You can have any name you want instead of 'showLoginError'
            title: 'Login Failed',
            message: 'Failed to authenticate',
            type: 'error' // You also can use 'VueNotifications.types.error' instead of 'error'
          }
        }
      }

    And then call it via this: this.showLoginError(), and also with some override props: this.showLoginError({message: 'whatever'}).

    Why do we need third-party UI lib (like mini-toastr)?

    Well, because we want to be agnostic. That's mean that if at some step you would be fucked up with your UI library, vue-notifications will allow you to replace it as much easy as possible. Basically you would be required to replace vue-notifications's config. And that's all.

    Installation

    Check the Docs: Installation

    npm i vue-notifications --save

    or

    yarn add vue-notifications

    include in project:

    Getting started

    Check the Docs: Getting started

    import VueNotifications from 'vue-notifications'
     
    Vue.use(VueNotifications, options)

    Setup and configuration (necessary)

    As I said above - you have to use UI library that would draw actual notifications for you.

    For this example I will use mini-toastr

    Step-by-step guide

    Let's do everything together

    If you don't want spend too much time with this shit - you can go ahead and copy-past whole code from the bottom of this page

    Anyway

    • Import vue-notifications

    Here we're including vue-notifications and mini-toastr in our project

    import VueNotifications from 'vue-notifications'
    import miniToastr from 'mini-toastr'

    P.S. don't forget to install mini-toastr (npm i mini-toastr --save)

    • Setup types of the messages

    This one is mostly related to mini-toastr. We basically want mini-toastr to have these 4 types of messages. Basically 'error' should be red and success - 'green'

    const toastTypes = {
      success: 'success',
      error: 'error',
      info: 'info',
      warn: 'warn'
    }
    • Activate mini-toastr

    Here we make mini-toasr initialization with types from above

    miniToastr.init({types: toastTypes})
    • Map vue-notification to mini-toastr

    We want our messages to be called via vue-notificationbut be shown by mini-toastr, So :

    function toast ({title, message, type, timeout, cb}) {
      return miniToastr[type](message, title, timeout, cb)
    }
     
    const options = {
      success: toast,
      error: toast,
      info: toast,
      warn: toast
    }

    This stuff will forward our messages, so in case of 'success', it will call miniToastr.success(message, title, timeout, cb), in case of 'error' it will call miniToastr.error(message, title, timeout, cb) and etc. Keep in mind that the types(like "success", "error" and etc) could be whatever you want. In this example we just use default stuff for both libs.

    • Activate the plugin

    Okay, now we have to pass our options into the plugin. Actually vue-notification has auto-install, but we want to pass options from above to it, so that's the case why do we do this manually

    Vue.use(VueNotifications, options)
    All together

    You can just copy-paste code below

    import VueNotifications from 'vue-notifications'
     
    // Include mini-toaster (or any other UI-notification library)
    import miniToastr from 'mini-toastr'
     
    // We shall setup types of the messages. ('error' type - red and 'success' - green in mini-toastr)
    const toastTypes = {
      success: 'success',
      error: 'error',
      info: 'info',
      warn: 'warn'
    }
     
    // This step requires only for mini-toastr, just an initialization
    miniToastr.init({types: toastTypes})
     
    // Here we are seting up messages output to `mini-toastr`
    // This mean that in case of 'success' message we will call miniToastr.success(message, title, timeout, cb)
    // In case of 'error' we will call miniToastr.error(message, title, timeout, cb)
    // and etc.
    function toast ({title, message, type, timeout, cb}) {
      return miniToastr[type](message, title, timeout, cb)
    }
     
    // Here we map vue-notifications method to function abowe (to mini-toastr)
    // By default vue-notifications can have 4 methods: 'success', 'error', 'info' and 'warn'
    // But you can specify whatever methods you want.
    // If you won't specify some method here, output would be sent to the browser's console
    const options = {
      success: toast,
      error: toast,
      info: toast,
      warn: toast
    }
     
    // Activate plugin
    // VueNotifications have auto install but if we want to specify options we've got to do it manually.
    Vue.use(VueNotifications, options)

    Usage

    Check the Docs: Usage

    export default {
        name: 'DemoView',
        data () {
          //...
        },
        methods: {
          //...
        },
        notifications: {
          showLoginError: { // You can have any name you want instead of 'showLoginError'
            title: 'Login Failed',
            message: 'Failed to authenticate',
            type: 'error' // You also can use 'VueNotifications.types.error' instead of 'error'
          }
        }
      }

    Now you can call showLoginError as a common method via this:

    this.showLoginError()

    PRO tip: Technically there is no difference between methods defined in notifications: {...} section and in methods: {...} section - they are all the same. So that's basically mean that** you shall not define methods with same name in those sections**, because they would overlap each other.

    So, now you can do something like that:

    methods: {
      login () {
        loginUtil.login(err => if (err) this.showLoginError())
      }
    }

    But wait. What if I want to show some custom message in example above?

    Well, in this case you can override showLoginError() method:

    this.showLoginError({message: err.message})

    In the same way you can override all the others properties

    this.showLoginError({title: 'my title', message: 'just an error', type: 'warn', timeout: 1000})

    Options to override

    As I said above, you can specify any of following properties

    Name Type Default value Description
    title String undefined Notification's title (can be empty)
    message String undefined Notification's body message. Normally should be set up
    timeout Number 3000 time before notifications gone
    cb Function undefined Callback function

    But actually you can add your own properties as well, if you want. Why and how? You can check it in Advanced Setup section.

    Browsers support.

    Check the Docs: Browsers support

    Version v1.0.0 and after guarantees only a support of evergreen browsers.

    Versions below v1.0.0 supports all ES5-compatable browsers (i.g. starting from IE11).

    License

    MIT License

    Copyright (c) 2016 Sergei Panfilov

    Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

    The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

    Install

    npm i vue-notifications

    DownloadsWeekly Downloads

    5,631

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    1.53 MB

    Total Files

    53

    Last publish

    Collaborators

    • se-panfilov