National Park of Minnesota

    breadstick

    0.2.15 • Public • Published

    🚀 A simple and flexible implementation of toast style notifications for Vue.js.

    All Contributors


    Breadstick

    A simple and flexible implementation of toast style notifications for Vue.js.

    🌟 Inspired by toasted-notes for React - which I think is really cool. ❤️

    Demo

    🌟 Features

    • An imperative API. This means that you don't need to set component state or render elements to trigger notifications. Instead, just call a function. This makes it very user friendly for component library authors.
    • Render whatever you want. Utilize the render callback to create entirely custom notifications.
    • Functional default styles. Import the provided css for some nice styling defaults or write your own styles.
    • JS agnostic notifications. Breadstick can be incrementally adopted to your application since it uses the already progressive Vue.js under the hood.

    📚 Table of Contents

    🥳 Breadstick Starters

    Here are a few Codesandbox starters you can use to get started with Breadstick in your Vue or Nuxt App.

    ⚡️ Installation

    Install breadstick and its peer dependency, animejs, using yarn or npm.

    npm install breadstick animejs --save

    You can then register BreadstickBakery as a Vue plugin.

    import Vue from 'vue'
    import { BreadstickBakery } from 'breadstick'
     
    // This exposes `this.$breadstick` in your Vue template.
    Vue.use(BreadstickBakery)

    Installing with Nuxt

    After installing Breadstick, we import it and register it as a client-side plugin. This is because Breadstick it makes use of some DOM APIs. Code is similiar to the Vue plugin shown above.

    🤖 Examples

    Breadstick can be used to render different types of notifications out of the box. You can render simple string notifications as well as custom styled notifications. This makes it really convenient.

    🍊 Basic usage

    Invoke a notification using the notify method to display a message to the user. Breadstick defaults the notification duration to 5 seconds in the top position.

    this.$breadstick.notify('🥞 Show me the pancakes')

    📚 Using different positions

    You can display notifications in different positions, including top-left, top, top-right, bottom-left, bottom, and bottom-right.

    [
      'top-left', 
      'top', 
      'top-right', 
      'bottom-left', 
      'bottom', 
      'bottom-right'
    ].forEach(position => {
      this.$breadstick.notify("Using position " + position, {
        position
      })
    })

    🏠 Using custom element

    With JSX or Vue's render function, breadstick is able to render a custom element or Vue component

    this.$breadstick.notify(
      <div>I am a custom HTML element</div>
    )

    📭 Close all notifications

    You can clear all notifications by calling breadstick's closeAll method

    this.$breadstick.closeAll()

    🏗 Advanced usage

    Whereas breadstick shines in making simple notifications for your Vue app, it's real strength is shown in allowing you to create custom notifications through it's render function callback.

    This is particularly useful if you want use custom themed elements or Vue components inside of your toast notification. In the following snippet, we render a custom Alert component to display a toast notification.

    This is particularly useful for building your own themed notification component library.

    Here are some examples of how to use breadstick to render you own custom element.

    🌮 With Vue's render function callback

    Breadstick exposes Vue's createElement function in the render callback that you can use to render your own components in a toast notification. This can be useful in a context where Vue's this context may not be available.

    In a Vue component, you can even use that component's this.$createElement to render your own element/component and return it in the render function callback so breadstick can display it.

    // Import your custom `Alert` component and render it in breadstick
    import Alert from './components/Alert'
     
    export default {
      mounted () {
        this.$breadstick.notify(({ h, onClose }) => {
          return h(Alert, {
            on: {
              click: onClose
            }
          }, 'A render function Alert notification')
        })
      }
    }

    🚚 With JSX

    You can also use JSX if you like :).

    // Import your custom `Alert` component and render it in breadstick
    import Alert from './components/Alert'
     
    export default {
      mounted () {
        breadstick.notify(({ onClose }) => {
          return (
            <Alert onClick={onClose}>
              An JSX Alert notification
            </Alert>
          )
        }
      }
    }

    💼 API

    notify(String|VNode|Function, options)

    • Arguments
      • { String | VNode | Function } Message
      • { Object } options

    Breadstick's notify method accepts two parameters. The first parameter can be a String, VNode (Object), or Function and the second is the options object.

    If a string is passed in the first argument, breadstick will render a notificiation with the string in the top center position with it's default internal component.

    this.$breadstick.notify('Simple notification.')

    If a VNode is passed, Breadstick treats it like a rendered component and renders it instead.

    this.$breadstick.notify(
      <div>I am a custom HTML element</div>
    )

    If a callback Function is passed in the first argument, it will expose an object with two parameters: h and the onClose which are both functions. Using a render callback allows you to tap into the close function. It's your best option if you want to completely re-style your toast notification

    this.$breadstick.notify(({ h, onClose }) => {
      return h('div', 'My custom notification')
    })

    Options

    Option Type Default Values
    position String top top, right, bottom, left, top-left, top-right, bottom-right, bottom-left
    duration Number 5000 Any number in milliseconds

    closeAll()

    • Type: Function The closeAll method closes all toast notifications that are visible in the UI at the time of invocation. Nice a succinct way to dismiss all notifications

    🔖 TODO:

    Breadstick still has a few more features coming up. These include:

    • Indefinitely display toast notification
    • Allow sharing of same application Vue instance.

    🤝 Contributing

    Here's our contribution guide.

    ❤️ Support this project

    If you like this project, please consider supporting it by buying my a coffee!

    Buy me a coffee
    Made with ❤️ by Jonathan Bakebwa 🇺🇬

    Contributors ✨

    Thanks goes to these wonderful people (emoji key):


    Jonathan Bakebwa

    💻 📖

    Omereshone Kelvin Oghenerhoro

    📖

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i breadstick

    DownloadsWeekly Downloads

    1,767

    Version

    0.2.15

    License

    MIT

    Unpacked Size

    61.3 kB

    Total Files

    49

    Last publish

    Collaborators

    • _codebender828