x-toast.js Library Documentation

Introduction

x-toast.js is a lightweight toast notification library for JavaScript that allows you to display customizable toast messages in various styles (info, success, warning, error). The library supports custom configuration, animations, and callbacks.

CDN Integration

To use x-toast.js, include the following links in your project:

JS and CSS via Bundle:

<script src="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/bundle.js"></script>

Individual Links:

<script src="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/toast.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/knighttower@latest/packages/toast/dist/browser/style.css">

Via npm

npm i @knighttower/toast

or from the monorepo

npm i knighttower

Basic Usage

// Example toast messages:
$toast.info('This is an info message.');
$toast.success('This is a success message.');
$toast.warning('This is a warning message.');
$toast.error('This is an error message.');

Methods

1. $toast.info(message, duration)

• Displays an info toast.
• message (String): The message text.
• duration (Integer, optional): Display time in milliseconds.

2. $toast.success(message, duration)

• Displays a success toast.

3. $toast.warning(message, duration)

• Displays a warning toast.

4. $toast.error(message, duration)

• Displays an error toast.

5. $toast.config(options)

• Set global configuration options.

Options:

$toast.config({
  classname: 'custom-class',
  transition: 'fade',
  position: 'top-left',
  autoClose: true,
  duration: 5000,
  progressBar: true,
  insertBefore: false,
  onShow: function(type) { console.log(`${type} toast shown`); },
  onHide: function(type) { console.log(`${type} toast hidden`); },
});

Configurations

| Option | Type | Description | Default Value | |--------------|----------|------------------------------------------------------------------------------------------------------|----------------| | classname | String | Additional class name for the toast container. | 'x' | | transition | String | CSS transition name (fade, slide-left-right, slide-up-down, etc.). | 'slide-left-right' | | position | String | Toast position (top-right, top-left, bottom-right, bottom-left). | 'top-right' | | duration | Integer | Duration in milliseconds. 0 calculates duration based on message length. | 3000 (3 sec) | | autoClose | Boolean | Enables/disables automatic closing of the toast message. | true | | progressBar| Boolean | Shows/hides the progress bar. Enabled only if autoClose is true. | true | | insertBefore| Boolean | Adds the new toast before/after existing toasts. | true | | onShow | Function | Callback function executed when the toast appears. | function() {}| | onHide | Function | Callback function executed when the toast disappears. | function() {}|

Transitions

| Transition Name | Description | |---------------------|------------------------| | fade | Fades in/out the toast. | | slide-left-right | Slides from the right. | | slide-right-left | Slides from the left. | | slide-up-down | Slides down from the top. | | slide-down-up | Slides up from the bottom. |

Positions

| Position Name | Location in Viewport | |-------------------|--------------------------| | top-right | Top-right corner | | top-left | Top-left corner | | bottom-right | Bottom-right corner | | bottom-left | Bottom-left corner |

Example

1. Simple Notification

$toast.success('Data saved successfully!', 4000);

2. Custom Configuration

$toast.config({
  position: 'bottom-right',
  transition: 'slide-up-down',
  duration: 5000,
  progressBar: false,
});
$toast.info('This is a custom info message.');

3. Callback Example

$toast.config({
  onShow: (type) => console.log(`Toast type: ${type} displayed`),
  onHide: (type) => console.log(`Toast type: ${type} hidden`)
});
$toast.warning('Warning with callbacks!');

CSS Customization

To customize transitions, follow the naming convention:

• {transition-name}--init
• {transition-name}--show
• {transition-name}--hide

Example:

/* Custom fade transition */
.x-toast.fade--init { opacity: 0; }
.x-toast.fade--show { opacity: 1; transition: opacity 0.5s ease-in; }
.x-toast.fade--hide { opacity: 0; transition: opacity 0.5s ease-out; }