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:

Download Butterup

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,
});

Top Left
Top Center
Top Right
Bottom Left
Bottom Center
Bottom Right

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',
});

Success
Warning
Error
Info
Success With Icon
Warning With Icon
Error With Icon
Info With Icon

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

Success Glass
Warning Glass
Error Glass
Info Glass
Success Brutalist
Warning Brutalist
Error Brutalist
Info Brutalist

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{
    
}