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/toastIf 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 git@gitlab.com:billow-thunder/toast.git
cd toast/demo
npm ci # Install against the package-lock
npx poi # Starts the dev-server at localhost:4000