Toast for Vue

Toast alerts/notifications for Vue apps. Originally authored by Yev Vlasenko, this clone only uses Velocity animations and adds additional features, such as shortcut prototypes and callback handling at toast and toaster level. It’s also designed specifically for Bulma, though it doesn’t enforce it – you can always provide your own styles.

Original package: https://github.com/euvl/vue-notification

Install

npm install --save @billow/toast

If you use NPM 5+, you can omit --save.

Usage

import Vue from 'vue'
import Toast from '@billow/toast'

Vue.use(Toast)

Install the toaster in the app root (wherever Vue is mounted):

<!-- Default toaster -->
<toaster/>

<!-- If you need another group -->
<toaster group="french" />

<!-- if you need close buttons to appear on the toasts (the value will be used as the class) -->
<toaster close-button="delete" group="french" />

Pop a toast from a component:

this.$toast({
  group: 'french', // omit if you don't have a group name
  title: 'Important message',
  text: 'Toasty toast toast.',
  closeButton: 'delete', // defaults to false, and not available to the shortcut methods
});

If you’d like to change the prototype name, simple provide your own:

Vue.use(Toast, {
  name: 'bread'
})

// In your component
this.$bread(…)

In the same way, you can also change the container name:

Vue.use(Toast, {
  name: 'bread',
  containerName: 'basket'
})

// In your root
<basket/>

Props

All props are optional.

Name | Type | Default | Description -- | -- | -- | -- animation | Object | (see below) | Optional animation configuration callback | Function | false | The function to call when a toast in the toaster is clicked. See the callback example for more. classes | String/Array | 'toast' | List of classes that will be applied to toast element ease-enter | String | 'easeOutSine' | The easing function to call for the enter animation function on all toasts within the toaster ease-leave | String | 'easeInSine' | The easing function to call for the leave animation function on all toasts within the toaster delay | Number | 100 | The delay before the toast appears duration | Number | 4000 | Time in ms that toast stays visible (if negative, it will stay forever or until clicked) group | String | null | Name of the toaster (holds toasts), if specified max | Number | 3 | Maximum number of toast that can be shown in its toaster position | String/Array | 'bottom right' | Part of the screen where toast will pop out reverse | Boolean | false | Show toasts in reverse order in its toaster speed | Number | 375 | Animation speed in ms width | Number/String | 375 | Width of toaster – % or px CSS string or number.Valid values: '100%', '200px', 200

Default animation

{
  enter: element => {
    let height = element.clientHeight
    return {
      height: [height, 0],
      opacity: [1, 0]
    }
  },
  leave: {
    height: 0,
    opacity: [0, 1]
  }
}

$toast

this.$toast({
  group: 'french',
  type: 'info', // corresponds to a Bulma color (see the colours section)
  title: 'Look!',
  text: 'This is <em>italic</em>.',
  duration: 10000,
  speed: 1000
  data: {
    something: 'I’ll be available in a custom slot.'
  },

  // Callback to fire when toast is clicked
  callback: (toast, close) => {
    say('what!')
    close() // closes the toast
  }
})

Title and Text can be HTML.

Simplified $toast and prototype shortcuts

// Just a simple toast.
this.$toast('text')

// These are shortcut helpers for simple toasts.
this.$success('Operation was successful')
this.$warning('Warning emitted.')
this.$error('There was an error.')
this.$info('Some info.')
this.$log('Logging here.')

// If you'd like a title, pass it in as the first argument.
// This only works on the helpers above, and not on $toast.
this.$success('Done!', 'Operation was successful')

If you find a prototype shortcut is interfering with another prototype from another plugin, simply specify which ones you want at install-time:

Vue.use(Toast, {
  types: ['success', 'error']
})

As an alternative: If you need both a prototype shortcut and the interfering prototype, simply tell Toast to namespace the shortcuts:

Vue.use(Toast, {
  namespaced: true,
})

This will install the prototypes under the $toast namespace (or whatever you may have called it using the name option).

this.$toast.error(…)

You can also provide your own prototype shortcuts and use them:

Vue.use(Toast, {
  types: ['notify', 'moan']
})

this.$moan(':(', 'Something went wrong.')

You can add types to the existing ones:

Vue.use(Toast, {
  types: [...Toast.types, 'notify', 'moan']
})

If you do this, remember to add custom styles for them. If you don’t, the default style will be used.

And lastly, you can skip the prototypes altogether:

Vue.use(Toast, {
  types: []
})

This will mean that you can only use $toast directly.

Calling outside a component

If you’d like to make toast outside a component (like in a store module, for example), you can just call it on Vue.

import Vue from 'vue'

Vue.$toast(...)
Vue.$success(...)
// etc.

Groups

If you are planning to have two or more completely different types of toasts (for example, authentication error messages in the top center and generic app notifications in the bottom-right corner), specify group property on the toasts container (the toaster):

<toaster group="auth"/>
<toaster group="app"/>

this.$toast({
  type: 'error',
  group: 'auth',
  text: 'Invalid credentials.'
})

Position

The position toaster prop requires a string with 2 keywords for vertical and horizontal postion.

Format: "<vertical> <horizontal>".

• Horizontal options: left, center, right
• Vertical options: top, bottom

Default is "bottom right".

Example:

<toaster position="top left"/>

Styling

Styles are not loaded by default. However, Toast comes with a default stylesheet that makes use of Bulma. To use the stylesheet:

// ... Import anything Bulma related first (such as a custom scaffold, or the entire Bulma library)

@import '~@billow/toast/styles'

Colours

The following table shows which toast types are mapped wo which colours:

Type | Colour -- | -- default | $primary error | $danger info | $info log | $ark success | $success warning | $warning

Variables

You can override the following variables by declaring them before you import the stylesheet:

$toast-border-radius: $radius;
$toast-default-background-color: $primary;
$toast-default-text-color: $primary-invert;
$toast-font-size: 1rem;
$toast-left-border-width: 5px;
$toast-margin: 0 0.4rem 0.4rem;
$toast-padding: 0.75rem;
$toast-title-font-weight: $weight-bold;
$toast-z-index: 999;

Custom styling

You can add custom styles for toasts. Here's the SCSS structure:

.french-toast {
  // Style of the notification itself

  .toast-title {
    // Style for title line
  }

  .toast-content {
    // Style for content
  }

  &.french {
    /**
     * Style for specific type of toast that will be applied when you
     * call toast with the type parameter:
     *   this.$toast({ type: 'french', message: 'I’m French.' })
     */
  }
}

Use the classes prop to apply the style to all toasts within the toaster.

<toaster classes="french-toast"/>

Custom slots

A scoped slot named toast is available if you'd like to override the structure of a toast for a specific toaster.

Scope props:

Name | Type | Description -- | -- | -- toast | Object | The toast object close | Function | Closes the toast

Example:

<toaster group="french-toast" position="top center">
  <template slot="toast" slot-scope="props">
    <div class="notification-toast">
      <icon icon="bell lg" class="is-medium" />
      <div class="toast-content" @click="event(props.item, props.close)">
        <p class="has-text-weight-bold">{{ props.item.title }}</p>
        <div class="custom-template-text">{{ props.item.text }}</div>
      </div>
      <a @click="props.close" class="delete"></a>
    </div>
  </template>
</toaster>

Cleaning up

To remove all toasts, use clean: true parameter.

this.$toast({
  group: 'foo', // optional
  clean: true
})

Development

If you’d like to contribute to Toast, simply clone the package, install the demo dependencies, and run the demo.

git clone [email protected]:billow-thunder/toast.git
cd toast/demo
npm ci # Install against the package-lock
npx poi # Starts the dev-server at localhost:4000