# Bootstrap Toaster

Robust, plug & play generator for Bootstrap toasts.

## Getting Started

    myButton.onclick = () => {
        let toast = {
            title: "Voila!",
            message: "How easy was that?",
            status: TOAST_STATUS.SUCCESS,
            timeout: 5000
        }
        Toast.create(toast);
    }

    $.ajax({
        type: "POST",
        url: "https://some-web-api/endpoint",
        data: {
            ...
        },
        success: function (response) {
            let toast = {
                title: "Success",
                message: response,
                status: TOAST_STATUS.SUCCESS,
                timeout: 10000
            }
            Toast.create(toast);
        },
        error: function (response) {
            console.error(response);
            let toast = {
                title: "Error",
                message: response,
                status: TOAST_STATUS.DANGER
            }
            Toast.create(toast);
        }
    });

Creating a toast is simple. All you need is a call to Toast.create() to get started. Simply pass an object with the following properties

1. title: The text of the toast's header.
2. message: The text of the toast's body. Supports plain text and HTML!
3. status: The status/urgency of the toast. Affects status icon and ARIA accessibility features. Optional, and defaults to 0, which renders no icon and has the same ARIA attributes as success and info toasts
4. timeout: Time in ms until toast disappears automatically. Optional, and defaults to 0, in which case the toast must be manually dismissed.

There are 4 built-in options for toast status, named after Bootstrap's color convention. They are as follows:

Set Timeout (sec)

## Placement

    Toast.setPlacement(TOAST_PLACEMENT.MIDDLE_CENTER);

By default, the toast container will be fixed to the top right corner of the screen on larger screen sizes, and top center on mobile. The Toast.setPlacement() function allows that positioning to be customized. Modifying placement is unique in that it will affect toasts that have already been rendered, because it moves the entire toast container. Top right and top center are most commonly used for notifications, but each of the following placements is supported:

Click each button to move the toast container!

## Theming

    Toast.setTheme(TOAST_THEME.LIGHT);

In supported browsers and operating systems, toasts will automatically choose a theme based on the user's OS settings. 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! Each toast created after the function is called will have the new theme, but previously rendered toasts will not change themes. Try it out below:

## Maximum Toast Count

    Toast.setMaxCount(6);
    Toast.enableQueue(true);

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.

Additionally, toasts can enter a queue when the limit is reached to be rendered as existing toasts disappear. This queue is enabled by default, and can be changed with Toast.enableQueue()

Set Max Count

## Toast Timers

    Toast.enableTimers(TOAST_TIMERS.ELAPSED);
    Toast.enableTimers(TOAST_TIMERS.COUNTDOWN);
    Toast.enableTimers(TOAST_TIMERS.DISABLED);

Toasts can display timers as well! By default, a toast will display the elapsed time since it was rendered, but a countdown timer is also available to show when the toast will disappear. Introducing Toast.enableTimers():

## Choosing the Right Version

Bootstrap Toaster offers versions for both Bootstrap 4 and Bootstrap 5! For Bootstrap 4 compatibility, use version 4.x, and for Bootstrap 5, use version 5.x. They are functionally identical and both fully supported!

## Accessibility

The toast container 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. Provided you properly use the statuses, all the accessibility work is done for you!