Toast

Toast delivers brief, non-blocking notifications that appear on screen to confirm actions, signal errors, or surface information. It supports five status variants, a built-in progress bar, position control, dismiss-previous behavior, and a static Toast.show() helper that requires no manual instantiation.

All active instances are tracked in a static Map, and each instance exposes .remove() and .dispose() for full lifecycle control.

Getting Started

Import the CSS, then call Toast.show() with a message and an optional status.

import { Toast } from 'frontalign';

Toast.show({
  message: 'Your changes have been saved.',
  status: 'success'
});

Structure

FrontAlign injects the toast element directly into document.body. No anchor element is required.

<div class="toast is-success is-bottom" role="status" aria-live="polite">
  <span class="toast-icon"></span>
  <span class="toast-message">Your changes have been saved.</span>
  <div class="toast-progress"></div>
</div>

Element	Class / Attribute	Purpose
Root	`.toast`	Outer wrapper injected into `document.body`. Receives status and position modifier classes.
Icon	`.toast-icon`	Status icon element. Rendered only when `showIcon` is `true`.
Message	`.toast-message`	Notification text content.
Progress bar	`.toast-progress`	Built-in countdown bar that animates linearly over the configured duration.

Status Variants

Toast ships with five status types. Each maps to a CSS modifier class on the root element.

Toast.show({ message: 'Record saved.',            status: 'success' });
Toast.show({ message: 'Connection failed.',        status: 'danger'  });
Toast.show({ message: 'Storage almost full.',      status: 'warning' });
Toast.show({ message: 'A new version available.',  status: 'info'    });
Toast.show({ message: 'General notification.',     status: 'default' });

Status	CSS Class	Use Case
`default`	`is-default`	General neutral notifications.
`success`	`is-success`	Confirmed actions, completed tasks.
`danger`	`is-danger`	Errors, failures, destructive events.
`warning`	`is-warning`	Potential issues, caution alerts.
`info`	`is-info`	Informational messages, tips.

Position

Toasts can be anchored to the top or bottom of the screen. The default is bottom.

Toast.show({ message: 'Appears at the top.',    position: 'top'    });
Toast.show({ message: 'Appears at the bottom.', position: 'bottom' });

Duration

Controls how long the toast stays on screen in milliseconds. Clamped between 1000 and 10000.

Toast.show({ message: 'Short toast.',   duration: 1000  });
Toast.show({ message: 'Default toast.', duration: 4000  });
Toast.show({ message: 'Long toast.',    duration: 10000 });

Dismiss Previous

Set dismissPrevious: true to remove all currently visible toasts before showing the new one.

Toast.show({
  message: 'Previous toasts in this position were removed.',
  status: 'info',
  position: 'bottom',
  dismissPrevious: true
});

Icon

Set showIcon: true to render a status icon inside the toast. By default no icon is shown.

Toast.show({ message: 'Toast with icon.',    status: 'success', showIcon: true  });
Toast.show({ message: 'Toast without icon.', status: 'default', showIcon: false });

Auto Clean

Set autoClean: true for fire-and-forget toasts. The instance calls .dispose() automatically after removal, freeing it from memory.

Toast.show({
  message: 'Toast instance auto-cleans after removal.',
  autoClean: true
});

Instance Methods

Method	Description
`.remove()`	Immediately removes the toast from the DOM and cancels the timer. Calls `.dispose()` automatically if `autoClean` is `true`.
`.dispose()`	Clears the timer, nullifies internal references, and removes the instance from `Toast.instances`.

const toast = new Toast({ message: 'Item deleted.', status: 'danger' });

// Later
toast.remove();

// Full cleanup
toast.dispose();

Static Instance Management

All active toast instances are stored in a static Map and accessible via Toast.instances.

// Inspect all active toasts
Toast.instances.forEach((instance, id) => {
  console.log(id, instance);
});

Configuration Reference

Option	Type	Default	Description
`message`	`string`	`"Hi, I am a toast message"`	Notification text displayed inside the toast.
`status`	`string`	`"default"`	Visual variant: `success`, `danger`, `warning`, `info`, or `default`.
`position`	`string`	`"bottom"`	Screen position: `top` or `bottom`.
`duration`	`number`	`4000`	Time in milliseconds before auto-dismiss. Clamped between `1000` and `10000`.
`dismissPrevious`	`boolean`	`false`	Removes all visible toasts before showing the new one.
`showIcon`	`boolean`	`false`	Renders a status icon inside the toast.
`autoClean`	`boolean`	`false`	Automatically calls `.dispose()` after the toast is removed.

Class Reference

Class	Element	Description
`.toast`	Root	Outer wrapper. Receives status and position modifiers.
`.is-success / .is-danger / .is-warning / .is-info / .is-default`	Root modifier	Status variant applied to the root element.
`.is-top / .is-bottom`	Root modifier	Position variant applied to the root element.
`.toast-icon`	Icon	Status icon. Present only when `showIcon` is `true`.
`.toast-message`	Message	Notification text content.
`.toast-progress`	Progress bar	Built-in countdown bar animated over the configured duration.