Robust, plug & play generator for Bootstrap toasts.
Built-in support for both light and dark themes. By default, the user's operating system preference will determine the theme, but this can be overridden. In an unsupported browser/OS combo, Bootstrap's default 'light' theme will take over.
On desktop, toasts will position themselves in the top right corner of the viewport, though this placement can be configured. Options include the four corners of the viewport. On mobile, the two top corners will result in a top-middle placement, and the bottom corners will result in a bottom-middle placement.
Toasts support options for how long they exist on the page before expiring automatically, or if they must be dismissed manually. Additionally, each toast displays the elapsed time since it was rendered, updated once per minute since it rendered. The elapsed timers are enabled by default but can be disabled too. Time to auto-hide a toast is per-toast and is set upon generation.
Too many toasts can overwhelm and annoy the user, so by default no more than 4 will be allowed to render on the page. For new ones to be generated, old ones must go. This maximum count is also configurable. In the event that the number of toasts overflows the height of the viewport, the toast container becomes scrollable too.
The container that houses all of the toasts is setup as an aria-live region, so changes to its descendant elements will alert screen readers. Success and Info toasts will read out when the user is not busy, leaving their flow uninterrupted, while Error and Warning toasts will read out immediately. In addition, all toast status icons and elapsed timers are hidden to screen readers, as they are purely visual indicators.
Setup is extremely straightforward. Simply include the CSS in your document's <head> and the JavaScript at the bottom of the <body> tag.
Install from npm, or via CDN. Currently jsDelivr is supported.
npm i bootstrap-toast.js
<head>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-toast.js@2.0.0/css/bootstrap-toast.min.css" />
</head>
<body>
...
<script src="https://cdn.jsdelivr.net/npm/bootstrap-toast.js@2.0.0/js/bootstrap-toast.min.js"></script>
</body>- jQuery (1.9.1 - 3.x), but only where it uses Bootstrap's own functions to create a toast
- Bootstrap (>= 4.2.1), for the toasts themselves
- Font Awesome (>= 5.0.0), for the toast status icons
Bootstrap-toast.js will take care of its own setup work, unless you choose to customize it, covered later on. When the script loads, it will insert a fixed position container into the DOM that will house all of your toasts when they appear, so you can get to generating toasts in a snap!
All it takes to generate one is a call to Toast.create(), like so:
Toast.create("Wow, that was easy!", "Just like that, this toast will appear on the page",
TOAST_STATUS.SUCCESS, 5000);The Toast.create() function supports the following 4 parameters:
-
title: The text of the toast's header. -
message: The text of the toast's body. -
status: The status/urgency of the toast. Affects status icon and ARIA accessibility features. Defaults to 0, which renders no icon. Default -> no status icon, same ARIA attributes as success and info toasts -
timeout: Time in ms until toast disappears automatically. Default -> 0, in which case the toast must be manually dismissed.
Since the invocation is so simple, you can generate a toast from anywhere or for anything! For example, here's how you might use it after using jQuery AJAX to post data to an API:
$.ajax({
type: "POST",
url: "https://some-web-api/endpoint",
data: {
...
},
success: function (response) {
response = JSON.parse(response);
Toast.create("Success", response.message, TOAST_STATUS.SUCCESS, 10000);
}
error: function (response) {
console.error(response);
Toast.create("Error", "Something went wrong.", TOAST_STATUS.DANGER);
}
});There are 4 built-in options for toast status in the call to Toast.create(), named after Bootstrap's color convention. They are as follows:
TOAST_STATUS.SUCCESSTOAST_STATUS.DANGERTOAST_STATUS.WARNINGTOAST_STATUS.INFO
As mentioned in the accessibility section, the status is important for correctly setting up ARIA attributes for the toast, but it also determines the toast's status icon.
While the status icons and timeouts are configurable per-toast, the other configuration options are applied globally, and have their own helper functions to accomplish this. You simply need to call them prior to calling Toast.create() for them to take effect on newly-generated toasts.
As mentioned in the prior section on theming, in supported browsers and operating systems the default behavior for toasts is to automatically choose a theme based on the user's preference at the OS level. However, there may be times where you want to force one theme or the other. In that case, the Toast.setTheme() function is for you! Here's how it works:
Toast.setTheme(TOAST_THEME.LIGHT);
// or
Toast.setTheme(TOAST_THEME.DARK);As the above script implies, there are two options for the lone theme parameter:
TOAST_THEME.LIGHTTOAST_THEME.DARK
In the unlikely event of forcing a theme, then wanting to leave it up to the user's preference again, calling Toast.setTheme() without any parameters will remove the forced theme settings from new toasts.
By default, the toast container will be fixed to the top right corner of the screen on larger screen sizes. The Toast.setPosition() function allows that positioning to be altered. The following example will move the toast container to the top left corner of the screen.
Toast.setPosition(TOAST_POSITION.TOP_LEFT);This function's lone position parameter supports the following options:
TOAST_POSITION.BOTTOM_LEFTTOAST_POSITION.BOTTOM_RIGHTTOAST_POSITION.TOP_LEFTTOAST_POSITION.TOP_RIGHT
Similar to the previous function, calling Toast.setPosition() with a null or missing parameter will restore the default top right configuration.
To avoid becoming a nuisance to users, especially if the creation of toasts is automated, a limit is in place to prevent too many toasts from being visible at once. By default, this limit is 4 toasts, but this can also be changed. The tool of choice is the Toast.setMaxCount() function. Below is an example of raising toast limit to 6 toasts.
Toast.setMaxCount(6);The lone maxToasts parameter supports any integer value greater than 0.
Perhaps you aren't a fan of the elapsed timers on each toast, or would like to save every resource you can by not running the timers in the background. Luckily, there's a function for that, too. Introducing Toast.enableTimers():
Toast.enableTimers(false);The lone enabled parameter simply accepts a boolean value, and defaults to true.
Suppose you would like to configure multiple global toast options at once. We have just the function for you! The Toast.configure() function exists as a quick shorthand to call each of the above config functions with a single call.
For example,
Toast.configure(5, TOAST_POSITION.BOTTOM_RIGHT, TOAST_THEME.DARK, false);In the above snippet, we have set the max toast count to 5, moved the toast container to the bottom right corner of the viewport, locked toasts to dark theme, and disabled elapsed timers on the toasts.
Toast.configure() supports the following parameters:
maxToasts: The maximum number of toasts allowed on the page at once.
position: The toast container's position, defaults to top right. This will not affect small screens in portrait.
theme: The toasts' theme, either light or dark. If unset, they will follow OS light/dark preference.
enableTimers: Controls whether elapsed time will be displayed in the toast header.
position and theme accept the same predefined options as mentioned in their respective sections, while maxToasts is an integer value and enableTimers is a boolean. Each parameter's default value is the same as in their respective helper functions.
With version 2.0, all the v1 functions have been deprecated in favor of a Toast class with static methods. This is to make distinguishing bootstrap-toast.js functions from other JavaScript easier. The old functions are still around and functions as wrappers for the new static methods, but will generate a console warning with each use. They will be removed with version 3.0. The deprecated functions are:
configureToasts()setMaxToastCount()setToastPosition()setToastTheme()enableToastTimers()toastGenerator()
Developed by Peyton Gasink, a senior in software engineering in Auburn University's class of 2020 as a COVID-19 quarantine project ❤️
Licensed under MIT License. For more information, refer to the LICENSE file within the GitHub repository.