Skip to content
This repository was archived by the owner on Jul 28, 2025. It is now read-only.

Global Toast Options

Jump to bottom
Peyton Gasink edited this page Sep 13, 2021 · 3 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.

Global Toast Options

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.

Contents

Light/Dark Theme Overrides

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:

  1. TOAST_THEME.LIGHT
  2. TOAST_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.

Toast Container Placement

By default, the toast container will be fixed to the top right corner of the screen on larger screen sizes. The Toast.setPlacement() function allows that placement to be altered. The following example will move the toast container to the top left corner of the screen.

Toast.setPlacement(TOAST_PLACEMENT.TOP_LEFT);

This function's lone placement parameter supports the following options:

  1. TOAST_PLACEMENT.TOP_LEFT
  2. TOAST_PLACEMENT.TOP_CENTER
  3. TOAST_PLACEMENT.TOP_RIGHT
  4. TOAST_PLACEMENT.MIDDLE_LEFT
  5. TOAST_PLACEMENT.MIDDLE_CENTER
  6. TOAST_PLACEMENT.MIDDLE_RIGHT
  7. TOAST_PLACEMENT.BOTTOM_LEFT
  8. TOAST_PLACEMENT.BOTTOM_CENTER
  9. TOAST_PLACEMENT.BOTTOM_RIGHT

Similar to the previous function, calling Toast.setPlacement() with a null or missing parameter will restore the default top right configuration.

Maximum Toast Count

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.

Toast Timers

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.

Configuration Shorthand

Suppose you would like to configure multiple global toast options at once. 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_PLACEMENT.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:

  1. maxToasts: The maximum number of toasts allowed on the page at once.
  2. placement: The toast container's placement, defaults to top right. This will not affect small screens in portrait.
  3. theme: The toasts' theme, either light or dark. If unset, they will follow OS light/dark preference.
  4. enableTimers: Controls whether elapsed time will be displayed in the toast header.

placement 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.

Clone this wiki locally