Butterup
Customisable & Lightweight JavaScript Toasts
Current Version: 2.0.0 | Last Updated: 09th July 2024
Introduction
This Vanilla JavaScript toast notification plugin is designed to seamlessly integrate into your workflow, adding a dash of style and simplicity to your user interface. Effortlessly configurable and delightfully lightweight, butterup ensures that your site's notifications are as smooth as butter.
Installation
butterup can be installed using yarn, npm, bun or as a vanilla JavaScript file. To install using one of these methods, run the following command:
npm i butteruptoasts
yard add butteruptoasts
bun add butteruptoasts
You will need to import the js and the css into your project once installed. If you have installed butterup via a package manager you will need to import the js and css as follows:
// In your JavaScript file
import butterup from 'butteruptoasts';
// In your CSS or JavaScript file
import 'butteruptoasts/dist/styles.css';
Alternatively, if you would like to download the vanilla JavaScript & CSS files to use in your project / application, you can do so by clicking the button below:
Usage
Render a toast notification
// Render a toast notification in the top-right corner of the screen
butterup.toast({
title: 'Hello World!',
message: 'This is a toast notification.',
location: 'top-right',
dismissable: false,
});
Rich Toasts
Render a toast notification with pre-determined styling for success, error, warning & info
// Render a success rich notification in the top-right corner of the screen
// Rich toasts have pre-determined icons that display if icon is set to true
butterup.toast({
title: '🎉 Hooray!',
message: 'Your payment was successful.',
location: 'top-right',
icon: false,
dismissable: false,
type: 'success',
});
Configuration
Butterup has some basic configuration options that allow you to adjust the max toasts to display at one time & the amount of time each toast is displayed for. The configuration options are as follows:
butterup.options.maxToasts: 5 // default
butterup.options.toastLife: 5000 // in ms
Location Options
Butterup allows you to render toast notifications in all four corners of the screen, as well as the center. The location option is a string that can be set to one of the following values:
'top-right' // default
'top-left'
'top-center'
'bottom-right'
'bottom-left'
'bottom-center'
Toast Variables
Butterup allows you to customize the title, message, icon, dismissable & type of toast notifications. The variables are as follows:
// title is the string that will be displayed as the title of the toast
title: 'Hello World!'
// message is the string that will be displayed as the message of the toast
message: 'This is a toast notification.'
// icon: boolean (only applicable for rich toasts currently)
icon: false
// dismissable: boolean (if set to true, the toast will close when clicked)
dismissable: false
// Rich toast types: 'success', 'error', 'warning', 'info'
type: 'success' // if no type is specified a generic toast will be shown
// Custom HTML can be added to the toast notification
customHTML: 'Add your custom HTML here',
// Custom icons can be added to the toast notification
customIcon: 'Add your raw SVG code here',
Event Triggers
Butterup allows you to trigger events when a toast is rendered, clicked or closed or when a toast times out. The event triggers are as follows:
butterup.toast({
// Event triggered when the toast is rendered
onRender: function(toast){
console.log('Toast rendered');
},
// Event triggered when the toast is clicked
onClick: function(event){
console.log('Toast clicked');
},
// Event triggered when the toast times out
onTimeout: function(toast){
console.log('Toast timed out');
},
// Event triggered when the toast is closed
onClose: function(toast){
console.log('Toast closed');
}
});
Buttons
Butterup allows you to add buttons to your toast notifications. The buttons can be styled and have event listeners attached to them. By default butterup supports a primary & secondary button for each toast, if you require more please use the customHTML attribute. The button object is as follows:
butterup.toast({
// A "primary" button item rendered with the toast with a click listener
primaryButton: {
text: 'Primary Button',
onClick: function(){
console.log('Primary Button Clicked');
}
},
// A "secondary" button item rendered with the toast with a click listener
secondaryButton: {
text: 'Secondary Button',
onClick: function(){
console.log('Secondary Button Clicked');
}
}
});
Themes
Butterup comes with three themes out of the box: standard, glass & brutalist. You can change them as follows:
// Theme names are: 'glass', 'brutalist'
theme: 'glass' // If no theme is defined, the standard theme will be used
Custom Themes
Butterup allows you to create your own themes for the toast notifications. You will need to make some adjustments to your CSS to style the notifications to your liking. To use your own theme do the following:
// Add a theme name to your toast object
theme: 'butterupcustom'
/* Add the following classes to your CSS file */
.butteruptoast.butterupcustom{
}
/* Butterup Custom Rich Notifications */
.butteruptoast.butterupcustom.success{
}
.butteruptoast.butterupcustom.error{
}
.butteruptoast.butterupcustom.warning{
}
.butteruptoast.butterupcustom.info{
}