Jquery Toast Plugin

Index

Quick Demos Some quick demos and the code to generate that, if you are in a hurry!
Generator A generator for you to easily generate the code for the kind of toast you want, so that you don't have to go through the documentation!
Options Each of the options is accompanied by a demo explaining that option.

Latest Update

Toast loader has been introduced in the latest version. Check the demo below to see it in action

Run code

$.toast('Here you can put the text of the toast')

Loader is enabled by default. In order to disable it or change the color, use the `loader` and `loaderBg` options. Have a look at the demo below

Run code

$.toast({
    heading: 'Information',
    text: 'Loaders are enabled by default. Use `loader`, `loaderBg` to change the default behavior',
    icon: 'info',
    loader: true,        // Change it to false to disable loader
    loaderBg: '#9EC600'  // To change the background
})

Quick Demos

To generate a most simple toast, all you have to do is

Run code

$.toast('Here you can put the text of the toast')

There are different kinds of toast types:

Run code

$.toast({
    heading: 'Information',
    text: 'Now you can add icons to generate different kinds of toasts',
    showHideTransition: 'slide',
    icon: 'info'
})

Run code

$.toast({
    heading: 'Error',
    text: 'Report any <a href="https://github.com/kamranahmedse/jquery-toast-plugin/issues">issues</a>',
    showHideTransition: 'fade',
    icon: 'error'
})

Run code

$.toast({
    heading: 'Warning',
    text: 'It is going to be supper easy for you to use ;)',
    showHideTransition: 'plain',
    icon: 'warning'
})

Run code

$.toast({
    heading: 'Success',
    text: 'And these were just the basic demos! Scroll down to check further details on how to customize the output.',
    showHideTransition: 'slide',
    icon: 'success'
})

Options

Of course that is not all what you can do using this plugin, there are a lot of other options. Let's start explaining each, one by one

You should note that, whenever you are going to use options, you have to pass an options object and specify the text as follows:

Run code

$.toast({
    text: 'This will become the toast message'
})

The text can be an array:

Run code

$.toast({
    heading: 'How to contribute?!',
    text: [
        'Fork the repository', 
        'Improve/extend the functionality', 
        'Create a pull request'
    ],
    icon: 'info'
})

Or put some HTML in the text

Run code

$.toast({
    heading: 'Can I add <em>icons</em>?',
    text: 'Yes! check this <a href="https://github.com/kamranahmedse/jquery-toast-plugin/commits/master">update</a>.',
    hideAfter: false,
    icon: 'success'
})

1. Specifying the heading of toast message

You can use the heading to set the heading property to set the heading of the toast message

Run Code

$.toast({
    heading: 'Headings',
    text: 'You can use the `heading` property to specify the heading of the toast message.',
})

2. Making them sticky:

There will be times, when you will want to have sticky toasts. To make them sticky, all you have to do is set the hideAfter to false. Here is a sticky toast

Run Code

$.toast({
    text: 'Set the `hideAfter` property to false and the toast will become sticky.',
    hideAfter: false
})

^* hideAfter property is basically used to set the timer after which the toast will get hidden. But you can set it to false in order to achieve the sticky toasts.

3. Changing the toast hide timer

You can use the property from the above option i.e. hideAfter to change the timer after which toast gets hidden. You have to specify the timer in milliseconds

Run Code

$.toast({
    text: 'Set the `hideAfter` property to milliseconds and the toast will hide after the specified milli seconds.',
    hideAfter: 5000   // in milli seconds
})

4. Changing the show/hide animation

You can use showHideTransition property to set the animation. Following are the available options:

fade for fade transitions
slide for slide up and down transitions
plain simple show from and hide to corner transition

Run Code

$.toast({
    text: 'Set the `showHideTransition` property to fade|plain|slide to achieve different transitions',
    heading: 'Slide transition',
    showHideTransition: 'slide'
})

Run Code

$.toast({
    text: 'Set the `showHideTransition` property to fade|plain|slide to achieve different transitions',
    heading: 'Fade transition',
    showHideTransition: 'fade'
})

Run Code

$.toast({
    text: 'Set the `showHideTransition` property to fade|plain|slide to achieve different transitions',
    heading: 'Plain transition',
    showHideTransition: 'plain'
})

5. Making the toast closeable or not

You can use allowToastClose to allow the user to close the toast or not. The only thing that this option does is make that little cross button show or hide itself

Run Code

$.toast({
    heading: 'Closeable Toast',
    text: 'Set the `allowToastClose` property to true|false to make the toast closeable or not',
    allowToastClose: true
})

Run Code

$.toast({
    heading: 'Non closeable Toast',
    text: 'Set the `allowToastClose` property to true|false to make the toast closeable or not',
    allowToastClose: false
})

6. Setting the toast stack

stack property can be used to specify how many maximum toasts you want to show at any point of time. By default this property is set to 5

Run Code

$.toast({
    heading: 'Stack',
    text: 'If set to a number, it will show that number of toasts at max at a time',
    stack: 4
})

Run Code

$.toast({
    heading: 'No stacking',
    text: 'If set to false, there will be only one toast at once.',
    stack: false
})

Note Hit the run button multiple times to test these demos.

7. Positioning the toast

position property can be used to specify the position. There are following predefined positions which you can use:

bottom-left value to show the toast at bottom left position
bottom-right value to show the toast at bottom right position
bottom-center value to..
top-right value to..
top-left value to..
top-center value to..
mid-center value to..
{ top: '-', bottom: '-', left: '-', right: '-' } javascript object with positioning properties as you set in CSS

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'Specify the custom position object or use one of the predefined ones',
    position: 'bottom-left',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'Specify the custom position object or use one of the predefined ones',
    position: 'bottom-right',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'Use the predefined ones, or specify a custom object',
    position: 'bottom-center',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'Use the predefined ones, or specify a custom object',
    position: 'top-left',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'از موارد از پیش تعریف شده استفاده کنید، یا یک موقعیت سفارشی را تعیین کنید',
    position: 'top-right',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'از موارد از پیش تعریف شده استفاده کنید، یا یک موقعیت سفارشی را تعیین کنید',
    position: 'top-center',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'از موارد از پیش تعریف شده استفاده کنید، یا یک موقعیت سفارشی را تعیین کنید',
    position: 'mid-center',
    stack: false
})

Run Code

$.toast().reset('all');$.toast({
    heading: 'Positioning',
    text: 'از موارد از پیش تعریف شده استفاده کنید، یا یک موقعیت سفارشی را تعیین کنید',
    position: {
        left: 120,
        top: 120
    },
    stack: false
})

Note It should be noted that, once you change the position of toast by using the `position` property, you'll have to reset the position for the next toasts, if you want them to appear at their default position i.e. the bottom left corner. Or else, each new toast generated will be appearing at the last position i.e. where you displayed the last positioned toast. You can reset the toast position by.

Run Code

$.toast().reset('all');

8. Messages with icons

icon property can be used to specify the predefined types of toasts. Following are the predefined types:

info generates a toast with information icon
warning generates a toast with warning icon
error generates a toast with error icon
success generates a toast with success icon

Run Code

$.toast({
    heading: 'Warning',
    text: 'Now you can seemlessly generate warnings using the icon property in the options',
    icon: 'warning'
})

Run Code

$.toast({
    heading: 'Success',
    text: 'Here is some kind of success message with a success icon that you can notice at the left side.',
    icon: 'success'
})

Run Code

$.toast({
    heading: 'Error',
    text: 'An unexpected error occured while trying to show you the toast! ..Just kidding, it is just a message, toast is right in front of you.',
    icon: 'error'
})

Run Code

$.toast({
    heading: 'Information',
    text: 'Now you can add icons to the toasts as well.',
    icon: 'info'
})

9. Background & text color

bgColor property is used to specify the background color of the toast message. Default is '#444'

textColor property is used to specify the text color of the toast message. Default is '#eee'

Run Code

$.toast({
    heading: 'Colors',
    text: 'Colors are specified using `bgColor` and `textColor` properties.',
    bgColor: '#FF1356',
    textColor: 'white'
})

10. Setting the text alignment

textAlign property is used to set the alignment of text inside the toast. Permitted values are:

left
right
center

Run Code

$.toast({
    text: 'Processing! Please wait..',
    textAlign: 'center'
})

11. Toast Events

Toast exposes the following events for you to bind to whatever you want

beforeShow will be triggered right before the toast is about to appear
afterShown will be triggered after the toast has appeared
beforeHide will be triggered before the toast is about to hide
afterHidden will be triggered right after the toast gets hidden

Run Code

$.toast({
    text: 'Triggers the events',

    beforeShow: function () {
        alert('The toast is about to appear');
    },

    afterShown: function () {
        alert('Toast has appeared.');
    },

    beforeHide: function () {
        alert('Toast is about to hide.');
    },

    afterHidden: function () {
        alert('Toast has been hidden.');
    }
})

12. Updating Toasts

If you have a reference to a toast and want to update that, you can do so by calling the update method on the instance.

Run Code


var myToast = $.toast({
    heading: 'Information',
    text: 'Here is some information that will be later on turned to an error',
    icon: 'info',
    hideAfter: false
});

// Update the toast after three seconds.
window.setTimeout(function(){
    myToast.update({
        heading: 'Error',
        text: 'Here is an information that changed to error',
        icon: 'error',
        hideAfter: false
    });    
}, 3000)

13. Resetting Toasts

If you have the reference to a specific toast, you can reset that by doing the following


var myToast = $.toast('Some toast that needs to be removed.');
myToast.reset(); // remove the toast "Some toast that needs to be removed"

If you do not have the reference to a specific toast and want to reset every toast, do the following:


$.toast().reset('all');

Customize Plugin

Text

Heading

Transition

Allow Toast Close

Auto Hide

Hide (with transition^) after (ms)

Stack toasts

Stack Length

Toast Position

Icon

Text Alignment

Toast Events

Show Loader

Loader Color

Generate


$.toast({
    text: "Hey there fellas, here is a simple toast. Change the options above and then see the code that generates that toast", // Text that is to be shown in the toast
    heading: 'How to use', // Optional heading to be shown on the toast
    icon: 'warning', // Type of toast icon
    showHideTransition: 'fade', // fade, slide or plain
    allowToastClose: true, // Boolean value true or false
    hideAfter: 3000, // false to make it sticky or number representing the miliseconds as time after which toast needs to be hidden
    stack: 5, // false if there should be only one toast at a time or a number representing the maximum number of toasts to be shown at a time
    position: 'bottom-left', // bottom-left or bottom-right or bottom-center or top-left or top-right or top-center or mid-center or an object representing the left, right, top, bottom values
    position: { left : 20, right : 20, top : 20, bottom : 20 }, // bottom-left or bottom-right or bottom-center or top-left or top-right or top-center or mid-center or an object representing the left, right, top, bottom values
    bgColor: '#444',  // Background color of the toast
    textColor: '#eee',  // Text color of the toast
    textAlign: 'left',  // Text alignment i.e. left, right or center
    loader: true,  // Whether to show loader or not. True by default
    loaderBg: '#9EC600',  // Background color of the toast loader
    beforeShow: function () {}, // will be triggered before the toast is shown
    afterShown: function () {}, // will be triggered after the toat has been shown
    beforeHide: function () {}, // will be triggered before the toast gets hidden
    afterHidden: function () {}  // will be triggered after the toast has been hidden
});