Description

The Toast component provides a way to display short-lived notifications to users. Toasts appear in a corner of the screen, can be configured with different positions, and can optionally include action and close buttons. Toasts can be set to automatically close after a specified timeout or remain until manually dismissed.

Basic Usage

<button id="example1">Open Toast</button>
<script type="module">
  import Toast from '/src/components/Toast.js';
  document.getElementById('example1').addEventListener('click', () => {
    Toast.create("Hello World");
  });
</script>

Different Positions

Toasts can be positioned in different corners of the screen using the position property.

<button id="example2-topleft" class="mb">Top Left</button>
<button id="example2-topcenter" class="mb">Top Center</button>
<button id="example2-topright" class="mb">Top Right</button><br />
<button id="example2-bottomleft" class="mb">Bottom Left</button>
<button id="example2-bottomcenter" class="mb">Bottom Center</button>
<button id="example2-bottomright" class="mb">Bottom Right</button>
<script type="module">
  import Toast from '/src/components/Toast.js';
  document.getElementById('example2-topleft').addEventListener('click', () => {
    Toast.create("Hello Top Left", {
      position: "top left"
    });
  });
  document.getElementById('example2-topcenter').addEventListener('click', () => {
    Toast.create("Hello Top Center", {
      position: "top center"
    });
  });
  document.getElementById('example2-topright').addEventListener('click', () => {
    Toast.create("Hello Top Right", {
      position: "top right"
    });
  });
  document.getElementById('example2-bottomleft').addEventListener('click', () => {
    Toast.create("Hello Bottom Left", {
      position: "bottom left"
    });
  });
  document.getElementById('example2-bottomcenter').addEventListener('click', () => {
    Toast.create("Hello Bottom Center", {
      position: "bottom center"
    });
  });
  document.getElementById('example2-bottomright').addEventListener('click', () => {
    Toast.create("Hello Bottom Right", {
      position: "bottom right"
    });
  });
</script>

Timeouts

Toasts can automatically close after a specified timeout (in milliseconds). The default timeout when using Toast.create is 5000 (ms), or 5 seconds.

<button id="example3-1">Open 1 Second Timeout Toast</button>
<button id="example3-3">Open 3 Second Timeout Toast</button>
<button id="example3-10">Open 10 Second Timeout Toast</button>
<script type="module">
  import Toast from '/src/components/Toast.js';
  document.getElementById('example3-1').addEventListener('click', () => {
    Toast.create("I will timeout in 1 second", {
      timeout: 1000
    });
  });
  document.getElementById('example3-3').addEventListener('click', () => {
    Toast.create("I will timeout in 3 second", {
      timeout: 3000
    });
  });
  document.getElementById('example3-10').addEventListener('click', () => {
    Toast.create("I will timeout in 10 second", {
      timeout: 10000
    });
  });
</script>

Action and Close Buttons

Toasts can have action and close buttons that trigger callbacks when clicked.

<button id="example4-action">Open Toast with Action</button>
<button id="example4-close">Open Toast with Close Button</button>
<button id="example4-action-close">Open Toast with Action and Close Button</button>
<script type="module">
  import Toast from '/src/components/Toast.js';
  document.getElementById('example4-action').addEventListener('click', () => {
    Toast.create("Hello World", {
      timeout: 0,
      action: 'Click Me',
      actionCallback: () => {
        Toast.create("You clicked the action");
      }
    });
  });
  document.getElementById('example4-close').addEventListener('click', () => {
    Toast.create("Hello World", {
      timeout: 0,
      close: '<k-icon name="close"></div>',
      closeCallback: () => {
        Toast.create("You closed the toast");
      }
    });
  });
  document.getElementById('example4-action-close').addEventListener('click', () => {
    Toast.create("Hello World", {
      timeout: 0,
      action: 'Click Me',
      actionCallback: () => {
        Toast.create("You clicked the action");
        return false; // return false to prevent closing
      },
      close: '<k-icon name="close"></div>',
      closeCallback: () => {
        Toast.create("You closed the toast");
      }
    });
  });
</script>

Success, Warning and Error

Toasts can be created as a success, warning or error message.

<button id="example5-success">Success Toast</button>
<button id="example5-warning">Warning Toast</button>
<button id="example5-error">Error Toast</button>
<script type="module">
  import Toast from '/src/components/Toast.js';
  document.getElementById('example5-success').addEventListener('click', () => {
    Toast.success("It Worked!");
  });
  document.getElementById('example5-warning').addEventListener('click', () => {
    Toast.warning("Be Careful");
  });
  document.getElementById('example5-error').addEventListener('click', () => {
    Toast.error("That's a very bad idea");
  });
</script>

JavaScript Reference

Constructor

Extends Component

new Toast()
new Toast(object options)

Parameters

options: object

An object with the following optional properties:

• actionCallback: function - Function to call when the action button is clicked. If this function returns false, the toast will not close.
• actionHtml: string - HTML content for the action button.
• closeCallback: function - Function to call when the toast is closed.
• closeHtml: string - HTML content for the close button.
• timeout: number - Time in milliseconds before the toast automatically closes. Default is 0 (no auto-close).

Static Methods

Toast.create(message, options): Toast

Creates and displays a new toast with the specified message and options. Returns the created Toast instance.

Options include:

• position: string - Position of the toast on the screen. Default is 'auto', which uses 'bottom center' on mobile and 'top right' on desktop. Valid positions are: 'top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'.
• removeOnClose: boolean - If true, the toast element will be removed from the DOM when closed. Default is true.
• timeout: number - Time in milliseconds before the toast automatically closes. Default is 5000ms (5 seconds).
• action: string | HTMLElement - Text or HTML element to use for the action button.
• actionCallback: function - Function to call when the action button is clicked. If this function returns false, the toast will not close.
• close: string | HTMLElement - Text or HTML element to use for the close button.
• closeCallback: function - Function to call when the toast is closed.
• icon: string | HTMLElement - Text or HTML element to use as an icon in the toast.

Toast.success(message, options): Toast

Creates and displays a success toast with a check icon and applies a success background style. Accepts the same options as Toast.create().

Toast.warning(message, options): Toast

Creates and displays a warning toast with a warning icon and applies a warning background style. Accepts the same options as Toast.create().

Toast.error(message, options): Toast

Creates and displays an error toast with an error icon and applies a danger background style. Accepts the same options as Toast.create().

Requirements

• ShadowComponent (configure ShadowComponent.pathToStylesheet as needed for your server)
• Icon

Properties

actionHtml: string

HTML content for the action button. Syncs to action-html attribute.

closeHtml: string

HTML content for the close button. Syncs to close-html attribute.

timeout: number

Time in milliseconds before the toast automatically closes. Default is 0 (no auto-close). Syncs to timeout attribute.

opened: boolean

Whether the toast is currently open. Default is false. Syncs to opened attribute.

actionCallback: function

Function to call when the action button is clicked.

closeCallback: function

Function to call when the toast is closed.

Methods

open(): void

Opens the toast. If a timeout is specified, this starts the timer for automatic closing.

close(): void

Closes the toast and calls the closeCallback if provided.

Events

open

Fired when the toast is opened.

close

Fired when the toast is closed.

openchange

Fired when the toast open state changes (both when opening and closing).

ToastContainer

The ToastContainer is an internal component used to position and display toasts. It is automatically created when Toast.create() is called, but can also be used directly.

new ToastContainer(position)

Creates a new toast container at the specified position.

position: string

The position of the container on the screen. Valid values are: 'top left', 'top center', 'top right', 'bottom left', 'bottom center', 'bottom right'.