Top

Usage

Toasts are an excellent way of providing feedback, or grabbing a users attention, for operations or actions that they have committed on the website. Toasts are also optional, and will disappear after a duration as to not interrupt their browsing experience.

To begin, a toast container needs to be initialized on the body.

$('body').toast();

Now that the container exists, we need to populate it with actual toasts. Since toasts represent actions, they cannot be automated and will need to be created manually.

Creating Toasts

Trigger the create() method on the toast instance to create a toast. This will display a popup within the container for a timed duration.

$('body').toolkit('toast', 'create', 'This will be the toast message!');

// Equivalent to
$('body').toolkit('toast').create('This will be the toast message!');
HTML can also be passed as the content, allowing for very complex and unique toasts to be displayed.

Dismissable Toasts

For situations where a toast needs to be displayed permanently until dismissed, an object of options can be passed as the 2nd argument to create() that disables the duration. A click event will also need to be bound to the toast to remove it.

// Grab the toast instance
var toast = $('body').toolkit('toast');

// Create a link and set a callback to remove the toast when clicked
var link = $('<a/>')
    .html('This is an important message!')
    .click(function() {
        toast.hide(this.parentNode); // Argument passed must be a .toast element
    });

// Create the toast
toast.create(link, { duration: 0 });
Top

ARIA

The log role on the container, and the note role on the toast, and the appropriate aria-* attributes are required when supporting ARIA.

<aside class="toasts" role="log">
    <div class="toast" role="note">
        ...
    </div>
</aside>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$toast-animations ("fade", "slide-up", "slide-down", "slide-left", "slide-right") A list of all animations to include in the CSS output.
$toast-class .toast CSS class name for the toast element.
$toast-class-wrapper .toasts CSS class name for the toasts wrapper.
$toast-position ("top-left", "top-center", "top-right", "center-left", "center-right", "bottom-left", "bottom-center", "bottom-right") A list of all positions to include in the CSS output.
$toast-transition .3s The transition time for toast reveal animations.
$toast-zindex 500 The z-index for the toasts container.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
animation string slide-up The animation to use when toasts are added to the container. Available options are: fade, slide-up, slide-down, slide-left, slide-right.
duration int 5000 The number in milliseconds before a toast disappears.
position string bottom-left Where to position the toasts container. Available options are: top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right.
template string <div class="toast"></div> The toast markup.
wrapperClass string toasts The class name to set on the composite wrapper.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
create element:toast Triggered after a toast is created but before it is shown.
hiding element:toast Triggered before a toast is hidden.
hidden Triggered after a toast is hidden.
showing element:toast Triggered before a toast is shown.
shown element:toast Triggered after a toast is shown.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description
element element The container element that all toasts are prepended to. It is fixed within the body.
Top

Methods

Inherits all methods from the parent Component.

Method Description
create(mixed:content[, object:options]) Creates a toast, sets the HTML to content, and initializes timers. Options can be customized by passing a second argument.
hide(element:toast) Hides the toast and sets an event that removes the element after the transition is complete. Is called automatically once the duration is over.
show(element:toast) Reveal the toast within the container. Is called automatically after the toast is created.