Toast

Send push notifications and alert messages with customizable templates and animations. Ideal for updates, alerts, and feedback messages.

ARIA design pattern

Getting started

Toast includes a container by default, so you don’t need to create it manually. However, if you want to customize the container, you can use this method to make changes.

Toast.container(({ position, name }) => {
  const nameClass = name ? `ui-toasts--${name}` : "";
  const positionClass = position ? `ui-toasts--${position}` : "";
  return `<div class="ui-toasts ${nameClass} ${positionClass}"></div>`;
});

If you want to set different layouts for the container, you can pass the name for it as the first argument and then use the container option when creating a toast.

Next, we need to set a template for the toast using the static ui-toast.template() method.

Toast.template(({ content, type, dismiss, autohide }) => {
  const className = `ui-toast ${type ? "ui-toast--" + type : ""}`;
  const closeBtn = dismiss ? `<button class="ui-btn-close ui-btn-close--no-bg" aria-label="Close" data-ui-dismiss />` : "";
  const progress = autohide ? '<div class="ui-toast-progress" data-ui-autohide-progress />' : "";
  return `<div class="${className}">${content}${closeBtn}${progress}</div>`;
});

Next, depending on the event, we create our toast, which will automatically appear in the default container and with the default template, unless we have specified different names.

new Toast({ type: "success", content: "Success message" });

You can also create your own function to make a toast, which will take an object with options and call the ui-toast constructor with them.

const showToast = (content, type) => {
  return new Toast({
    type,
    content,
    autohide: 5000,
    limit: 3,
    position: "bottom-end",
    breakpoints: {
      1024: {
        limit: 5,
        position: "top-end",
      },
    },
  });
};
 
const toast = {
  info: (content) => showToast(content, "info");
  success: (content) => showToast(content, "success");
  warning: (content) => showToast(content, "warning");
  error: (content) => showToast(content, "error");
};
 
toast.info("Info message");
toast.success("Success message");
toast.warning("Warning message");
toast.error("Error message");

Options

Name	Type	Default	Description
`init`	`Boolean`	`true`	Should the instance be automatically initialized when an instance is created? If `false`, you’ll need to manually initiate it by calling `ui-toast.init()`.
`destroy`	`Boolean`	`false`	Allows you to destroy an instance at a specific breakpoint.
`data`	`String`	`''`	Allows you to use the default options that have been added by the `ui-toast.data()` static method.
`on`	`Object`	`null`	Used to register event handlers.
`appear`	`Boolean`	`true`	If you want to apply a transition upon initialization as well, you can set this option to `true`.
`eventPrefix`	`String`	`'ui-toast:'`	Prefix for events dispatched on the `ui-toast` element.
`eventDispatch`	`Boolean, EventName`	`true`	Defines if events are dispatched or used only within options.
`eventBubble`	`Boolean, EventName`	`true`	Defines if events should bubble up the DOM.
`breakpoints`	`Object`	`null`	Defines custom options for specific breakpoints.
`shown`	`Boolean`	`null`	Defines if the toast is open after initialization. By default, it’s `null`, which means it checks the `hidden` attribute or another attribute, depending on `stateMode`.
`root`	`CSSSelector`, `Element`	`null`	By default, this is `null`. If the toast is in the DOM, it will stay in its place. If it is programmatically generated, it will be placed in the `body`.
`container`	`String`	`''`	Specifies the container template created with the static method `ui-toast.container()`.
`template`	`String`	`''`	Specifies the toast template created with the static method `ui-toast.template()`.
`limit`	`Number`	`5`	Determines the maximum number of toasts that can be displayed at the same time.
`limitAnimateEnter`	`Boolean`	`true`	Determines whether new toasts should be animated if the limit is exceeded.
`limitAnimateLeave`	`Boolean`	`true`	Determines whether old toasts should be animated if the limit is exceeded.
`ui-toastClassActive`	`String`	`'ui-active'`	CSS class for `ui-toast` element when it’s shown.
`dismiss`	`Boolean, CSSSelector`	`true`	Allows the toast to be hide when clicked on the button. By default, it’s `true`, meaning the `hide` method will be called when `'[data-ui-dismiss=""],[data-ui-dismiss="toast"]'` is clicked
`content`	`any`	`null`	Can contain anything, used only in `template`
`position`	`String`	`'top-end'`	How to position the container: Use `'top','bottom','left'`, or `'right'`. You can also append `'-start'` or `'-end'` to these positions, such as `'top-end'`.
`topLayer`	`Boolean`	`true`	Determines whether the `ui-toast` should be displayed in the top layer.
`keepTopLayer`	`Boolean`	`true`	Determines whether the `ui-toast` should be forced to the frontmost position in the top layer when other components are opened in front of it.

Autohide

Name	Type	Default	Description
`autohide`	`Boolean, Number, AutohideOptions`	`false`	Object with autohide options or boolean `true` to enable with default options. If a number is set, it will be passed to the `duration` option.

`duration`	`Number`	`0`	Sets the time in ms after which the toast will hide
`durationUpdate`	`Function`	`null`	The function is called each time the `progress` changes, passes arguments `{ elem, time, progress }`
`pauseOnMouse`	`Boolean`	`true`	Should the timer pause when we hover over the `ui-toast` with the mouse
`resetOnMouse`	`Boolean`	`true`	Should the timer reset when we hover over the `ui-toast` with the mouse
`pauseOnFocus`	`Boolean`	`true`	Should the timer pause when we focus on the `ui-toast`
`resetOnFocus`	`Boolean`	`true`	Should the timer reset when we focus on the `ui-toast`
`visibilityControl`	`Boolean`	`false`	Should the timer pause when the tab is not active
`cssVariable`	`String`	`'ui-progress'`	Name for the css variable, which will record the current progress

Name	Type	Default	Description
`a11y`	`Boolean, String, A11yOptions`	`'status'`	Object with `A11yOptions` or `true` to enable with default options. You can also use one of the following values: `'status'` or `'alert'`.

`role`	`String`	`'status'`	Adds the `role` attribute to the `ui-toast` element.
`ariaLive`	`String`	`'polite'`	Adds the `aria-live` attribute to the `ui-toast` element.
`ariaAtomic`	`Boolean`	`true`	Adds the `aria-atomic` attribute to the `ui-toast` element.

Defaults for the a11y:'status' value:

{
  role: 'status',
  ariaLive: 'polite',
}

Defaults for the a11y:'alert' value:

{
  role: 'alert',
  ariaLive: 'assertive',
}

Transition

Methods

method	return	description
`init()`	`instance`	Initializes the component.
`destroy(destroyOptions)`	`instance, null`	Destroys the component. Accepts an object as options `{ remove: false, keepInstance: false, keepState: false }`
`update(options)`	`instance`	Accepts options as an argument and updates the component.
`toggle(force, toggleOptions)`	`promise`	Toggles the component’s visibility state between shown and hidden.
`show(toggleOptions)`	`promise`	Shows the component. Accepts the same options as `toggle()` method
`hide(toggleOptions)`	`promise`	Hides the component. Accepts the same options as `toggle()` method

Class

method	return	description
`data(name?, callback)`	`Class`	Allows you to set default options for components that have the property `data:'name'`
`updateDefault(options)`	`default`	Updates default options
`initAll(root)`	`instance[]`	Searches for elements in `root`, which defaults to `document` with the attribute `data-ui-toast`
`get(id or elem)`	`instance`	Searches for an instance by `id` or `base` element
`getOrCreate(id or elem, options)`	`instance`	Searches for an instance by `id` or `base` element, if not found - creates a new instance with specified options
`container(name?, callback)`	`Class`	Creates a layout for the container
`template(name?, callback)`	`Class`	Creates a layout for the toast
`toggle(id, force, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `toggle()` method with the specified options
`show(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `show()` method with the specified options
`hide(id, toggleOptions)`	`promise`	Searches for an instance by `id` and calls its `hide()` method with the specified options

Properties

Name	Type	Description
`id`	`String`	The `id` of the `base` / `ui-toast` element.
`isInit`	`Boolean`	Indicates whether the instance is already initialized.
`opts`	`Object`	Contains the currently applied options for the current breakpoint.
`baseOpts`	`Object`	Contains all options, including the `breakpoints` option.
`base, toast`	`Element`	All components have a `base` property, which refers to the element through which the component is initialized and where events are fired. `ui-toast` is a synonym for `base`.

Class

Name	Type	Description
`Default`	`Object`	Default options
`instances`	`Map`	A `Map` that contains all instances of the component

Events

Name	Arguments	Description
`beforeInit`	`instance`	Event will fired right before initialization.
`init`	`instance`	Fires when initialization has been completed.
`beforeShow`	`instance, {trigger, event}`	Fires immediately when the `show()` method is called.
`show`	`instance, {trigger, event}`	Fires when the element becomes visible, but the CSS transition hasn’t started yet.
`shown`	`instance, {trigger, event}`	Fires when the CSS transition hasn’t been completed.
`beforeHide`	`instance, {trigger, event}`	Fires immediately when the `hide()` method is called.
`hide`	`instance, {trigger, event}`	Fires just before the CSS transition starts.
`hidden`	`instance, {trigger, event}`	Fires when the CSS transition has been completed.
`pause`	`instance`	Fires when the autohide timer is paused.
`resume`	`instance`	Fires when the autohide timer is resumed.
`reset`	`instance`	Fires when the autohide timer is reset.
`beforeDestroy`	`instance`	Fires before the instance is destroyed.
`destroy`	`instance`	Fires immediately when the `destroy()` method is called.
`breakpoint`	`instance, breakpoint, prevBreakpoint`	Fires when the breakpoint has been changed.
`any`	`eventName, instance`	Fires on any event occurrence. The first argument contains the name of the event.

Toast

Getting started

Options

Autohide

Accessibility (a11y)

Transition

Methods

Class

Properties

Class

Events