Overview #

What developer should know before using the toast plugin:

• For performance concerns, toasts are opt-in, therefore developer must initialize them manually.
• If developer does not set autohide: false, toasts will automatically disappear.

Examples #

Basic #

It is advised that a header and body to promote extendable and predictable toasts. Toast headers employ display: flex, which makes content alignment simple thanks to our flexbox and margin tools.

Toasts have very minimal necessary markup and are as versatile as developer need them to be. It is strongly recommended a dismiss button and only require a single element to contain your "toasted" information.

<div class="bd-example bg-light">
<div class="toast fade show" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <svg class="bd-placeholder-img rounded me-2" width="20" height="20" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" preserveAspectRatio="xMidYMid slice" focusable="false"><rect width="100%" height="100%" fill="#007aff"></rect></svg>

    <strong class="me-auto">UX4G</strong>
    <small>11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>
</div>

RESULT

Live example #

Click the button below to show a toast (positioned with our utilities in the lower right corner) that has been hidden by default.

<button type="button" class="btn btn-primary" id="liveToastBtn">Show live toast</button>

<div class="toast-container position-fixed bottom-0 end-0 p-3">
  <div id="liveToast" class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">UX4G</strong>
      <small>11 mins ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

RESULT

We use the following JavaScript to trigger our live toast demo:

const toastTrigger = document.getElementById('liveToastBtn')
const toastLiveExample = document.getElementById('liveToast')
if (toastTrigger) {
  toastTrigger.addEventListener('click', () => {
    const toast = new UX4G.Toast(toastLiveExample)

    toast.show()
  })
}

Translucent #

Toasts are slightly translucent to blend in with what’s below them.

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-header">
    <img src="..." class="rounded me-2" alt="...">
    <strong class="me-auto">UX4G</strong>
    <small class="text-muted">11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

RESULT

Stacking #

You can stack toasts by wrapping them in a toast container, which will vertically add some spacing.

<div class="toast-container position-static">
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">UX4G</strong>
      <small class="text-muted">just now</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      See? Just like this.
    </div>
  </div>

  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">UX4G</strong>
      <small class="text-muted">2 seconds ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Heads up, toasts will stack automatically
    </div>
  </div>
</div>

RESULT

Custom content #

Remove sub-components from the toasts, make changes with tools, or add own markup to personalize them. Here, simplified the toast by deleting the standard .toast-header, including a unique hide icon from UX4G Icons, and modifying the layout with some flexbox utilities.

<div class="toast align-items-center" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="btn-close me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

RESULT

Alternatively, you can also add additional controls and components to toasts.

<div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="toast-body">
    Hello, world! This is a toast message.
    <div class="mt-2 pt-2 border-top">
      <button type="button" class="btn btn-primary btn-sm">Take action</button>
      <button type="button" class="btn btn-secondary btn-sm" data-bs-dismiss="toast">Close</button>
    </div>
  </div>
</div>

RESULT

Color schemes #

Using the color and background utilities, developers can develop various toast color schemes based on the aforementioned example. It is added here. Add .btn-close-white to .btn and text-bg-primary to the .toast before adding the close button. With .border-0, we eliminate the default border for a clean edge.

<div class="toast align-items-center text-bg-primary border-0" role="alert" aria-live="assertive" aria-atomic="true">
  <div class="d-flex">
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
    <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
</div>

RESULT

Placement #

Place toasts using custom CSS where they are needed. Notifications are frequently displayed on the upper middle and top right. Put the placement styles directly on the .toast file if only ever going to display one toast at a time.

Consider utilizing a wrapper element for systems that produce more notifications so they can conveniently stack.

<form>
  <div class="mb-3">
    <label for="selectToastPlacement">Toast placement</label>
    <select class="form-select mt-2" id="selectToastPlacement">
      <option value="" selected="">Select a position...</option>
      <option value="top-0 start-0">Top left</option>
      <option value="top-0 start-50 translate-middle-x">Top center</option>
      <option value="top-0 end-0">Top right</option>
      <option value="top-50 start-0 translate-middle-y">Middle left</option>
      <option value="top-50 start-50 translate-middle">Middle center</option>
      <option value="top-50 end-0 translate-middle-y">Middle right</option>
      <option value="bottom-0 start-0">Bottom left</option>
      <option value="bottom-0 start-50 translate-middle-x">Bottom center</option>
      <option value="bottom-0 end-0">Bottom right</option>
    </select>
  </div>
</form>

RESULT

You can also get fancy with flexbox utilities to align toasts horizontally and/or vertically.

<!-- Flexbox container for aligning the toasts -->
<div aria-live="polite" aria-atomic="true" class="d-flex justify-content-center align-items-center w-100">

  <!-- Then put toasts within -->
  <div class="toast" role="alert" aria-live="assertive" aria-atomic="true">
    <div class="toast-header">
      <img src="..." class="rounded me-2" alt="...">
      <strong class="me-auto">UX4G</strong>
      <small>11 mins ago</small>
      <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
    </div>
    <div class="toast-body">
      Hello, world! This is a toast message.
    </div>
  </div>
</div>

RESULT

Accessibility #

For the benefit of those using screen readers and other assistive technology, developer should wrap the toasts in an aria-live region since they are meant to be brief interruptions to the visitors or users. Screen readers automatically communicate changes to live areas (such as injecting or updating a toast component) without needing to change the user's focus or otherwise interrupt the user. Incorporate aria-atomic="true" as well to make sure the entire toast is always announced as a single (atomic) unit as opposed to just announcing what was changed (which could cause issues if you only update a portion of the toast's content or if displaying the same toast content at a later time). Use the alert component rather than toast if the information required is crucial for the operation, such as a list of problems in a form.

Please take note that before the toast is generated or refreshed, the live region must exist in the markup. Assistive technologies won't typically announce them if dynamically generate both at once and inject them into the website.

The role and aria-live level must also be modified according to the material. Use the role="alert" and aria-live="assertive" attributes if the message is critical, such as an error, and the role="status" and aria-live="polite" attributes if it is not.

Be sure to update the delay timeout as the content displaying changes to give users adequate time to read the toast.

<div class="toast" role="alert" aria-live="polite" aria-atomic="true" data-bs-delay="10000">
  <div role="alert" aria-live="assertive" aria-atomic="true">...</div>
</div>

When using autohide: false, you must add a close button to allow users to dismiss the toast.

  <div role="alert" aria-live="assertive" aria-atomic="true" class="toast" data-bs-autohide="false">
  <div class="toast-header">
    <img src="..." class="rounded me-2" alt="...">
    <strong class="me-auto">UX4G</strong>
    <small>11 mins ago</small>
    <button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>
  </div>
  <div class="toast-body">
    Hello, world! This is a toast message.
  </div>
</div>

RESULT

Although it is technically feasible to include focusable/actionable controls (such as extra buttons or links) in the toast, developer should refrain from doing so for toasts that automatically hide. Since (toasts are not given focus when they are presented), keyboard and assistive technology users can have trouble getting to the toast in time to respond even if you give it a lengthy delay timeout. It is advised utilizing a toast with autohide: false if you really must have additional controls.

CSS #

Variables #

Toasts now leverage local CSS variables on.toast for improved real-time customization as part of UX4G's growing CSS variables strategy. Sass is used to set the values for the CSS variables, therefore Sass customization is still available.

  --#{$prefix}toast-zindex: #{$zindex-toast};
  --#{$prefix}toast-padding-x: #{$toast-padding-x};
  --#{$prefix}toast-padding-y: #{$toast-padding-y};
  --#{$prefix}toast-spacing: #{$toast-spacing};
  --#{$prefix}toast-max-width: #{$toast-max-width};
  @include rfs($toast-font-size, --#{$prefix}toast-font-size);
  --#{$prefix}toast-color: #{$toast-color};
  --#{$prefix}toast-bg: #{$toast-background-color};
  --#{$prefix}toast-border-width: #{$toast-border-width};
  --#{$prefix}toast-border-color: #{$toast-border-color};
  --#{$prefix}toast-border-radius: #{$toast-border-radius};
  --#{$prefix}toast-box-shadow: #{$toast-box-shadow};
  --#{$prefix}toast-header-color: #{$toast-header-color};
  --#{$prefix}toast-header-bg: #{$toast-header-background-color};
  --#{$prefix}toast-header-border-color: #{$toast-header-border-color};
  

Sass variables #

$toast-max-width:                   350px;
$toast-padding-x:                   .75rem;
$toast-padding-y:                   .5rem;
$toast-font-size:                   .875rem;
$toast-color:                       null;
$toast-background-color:            rgba($white, .85);
$toast-border-width:                $border-width;
$toast-border-color:                var(--#{$prefix}border-color-translucent);
$toast-border-radius:               $border-radius;
$toast-box-shadow:                  $box-shadow;
$toast-spacing:                     $container-padding-x;

$toast-header-color:                $gray-600;
$toast-header-background-color:     rgba($white, .85);
$toast-header-border-color:         rgba($black, .05);

Usage #

Initialize toasts via JavaScript:

const toastElList = document.querySelectorAll('.toast')
const toastList = [...toastElList].map(toastEl => new ux4g.Toast(toastEl, option))

Triggers #

Dismissal can be achieved with the data attribute on a button within the toast as demonstrated below:

<button type="button" class="btn-close" data-bs-dismiss="toast" aria-label="Close"></button>

or on a button outside the toast using the data-bs-target as demonstrated below:

<button type="button" class="btn-close" data-bs-dismiss="toast" data-bs-target="#my-toast" aria-label="Close"></button>

Options #

Data-bs-animation can have an option name appended to it, for example, data-bs-animation="{value}" since options can be provided through data attributes or JavaScript. When sending the choices via data attributes, be sure to modify the case type of the option name from "camelCase" to "kebab-case" Use data-bs-custom-class="beautifier" as opposed to data-bs-customClass="beautifier," for instance.

Since UX4G 1.0.0, all components have support for the experimental reserved data attribute data-bs-config, which can store a JSON string for basic component setting. When an element has the data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the individual data attributes will take precedence over the values specified on the data-bs-config. Additionally, JSON variables like data-bs-delay='{"show":0,"hide":150}' can be stored in existing data attributes.

Methods #

Events #

const myToastEl = document.getElementById('myToast')
myToastEl.addEventListener('hidden.bs.toast', () => {
  // do something...
})