Skip to content

Getting Started

Jump to bottom
Peyton Gasink edited this page Sep 13, 2021 · 4 revisions

Note: This page has not yet been updated to reflect changes in version 5.1.0. It will be updated following the release of 4.1.0. Until then, to see examples of new method signatures, refer to the demo page.

Contents

Getting Started

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-toaster

<head>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/css/bootstrap-toaster.min.css" />
</head>
<body>
  ...
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/js/bootstrap-toaster.min.js"></script>
</body>

Dependencies

Version 5.x

  1. Bootstrap 5 (>= 5.0.0-beta2), for the toasts themselves
  2. Bootstrap Icons (>= 1.3.0), for the toast status icons

Version 4.x

  1. jQuery (1.9.1 - 3.x), for Bootstrap's own functions to create a toast
  2. Bootstrap 4 (>= 4.2.1), for the toasts themselves
  3. Bootstrap Icons (>= 1.3.0), for the toast status icons

Minimal Required Setup

Bootstrap Toaster will take care of its own setup work. 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:

  1. title: The text of the toast's header.
  2. message: The text of the toast's body.
  3. 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
  4. 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);
    }
});

Toast Status Options

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.SUCCESS
  • TOAST_STATUS.DANGER
  • TOAST_STATUS.WARNING
  • TOAST_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.

Clone this wiki locally