API.md

Classes

ToastQueue

Typedefs

ToastQueueOptions : Object

Configuration options for a ToastQueue.

ToastQueuePosition : 'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end'

Position of the toast queue.

ToastQueueTemplate : Object

HTML templates used to render a toast queue.

Templates are expected to contain the data-part attributes used by the library to locate and update their elements.

ToastContent : string | ToastContentObject

Content displayed by a toast.

ToastContentObject : Object

ToastOptions : Object

Configuration for an individual toast.

ToastPriority : 'normal' | 'high'

Toast priority used for screen-reader announcements.

high requests a higher announcement priority from ariaNotify().

ToastAction : Object

Configuration for an optional toast action button.

ToastActionHandler ⇒ void

Called when a toast action button is clicked.

ToastCloseHandler ⇒ void

Called after a toast is closed and removed from the queue.

ToastRecord : Object

Record representing a toast managed by a ToastQueue.

CloseReason : 'timeout' | 'button' | 'escape' | 'swipe' | 'manual'

Reason a toast was closed.

ActivationReason : 'focus' | 'click'

Reason the queue becomes interaction-active.

ToastAddEventDetail : Object

Detail payload for the toast-add event.

ToastCloseEventDetail : Object

Detail payload for the toast-close event.

ToastActionEventDetail : Object

Detail payload for the toast-action event.

ToastActivateEventDetail : Object

Detail payload for the activate event.

ToastDeactivateEventDetail : Object

Detail payload for the deactivate event.

ToastQueue

Kind: global class

• ToastQueue
  • new ToastQueue([options])
  • .element : HTMLElement
  • .size : number
  • .position : ToastQueuePosition
  • .visibleLimit : number
  • .add(content, [options]) ⇒ ToastRecord
  • .get(id) ⇒ ToastRecord | undefined
  • .close(id, [reason]) ⇒ void
  • .clear() ⇒ void
  • .pause() ⇒ void
  • .resume() ⇒ void
  • .destroy() ⇒ void

new ToastQueue([options])

Manages a queue of toast notifications.

The queue handles rendering, auto-dismiss timers, pause/resume behavior, focus management, keyboard dismissal, pointer interaction, touch swipes, and screen-reader announcements.

Auto-dismiss timers are paused while the queue is hovered or focused and while the document is hidden.

Toasts are announced with the browser's ariaNotify() API when available. Browsers without ariaNotify() can use the @github/arianotify-polyfill before creating the queue.

The queue is unopinionated by default, with sensible core styles. Use the exposed data-* attributes and CSS custom properties to provide your own presentation, or use one of the optional CSS presets.

Public API

Methods

• add
• get
• close
• clear
• pause
• resume
• destroy

Properties

• element
• size
• position
• visibleLimit

Custom events

The queue dispatches the following bubbling custom events from its root <toast-queue> element:

• toast-add — ToastAddEventDetail Dispatched after a toast is added to the queue.
• toast-close — ToastCloseEventDetail Dispatched when a toast is closed.
• toast-action — ToastActionEventDetail Dispatched when a toast action button is clicked.
• activate — ToastActivateEventDetail Dispatched when the queue becomes interaction-active.
• deactivate — ToastDeactivateEventDetail Dispatched when the queue is no longer interaction-active.
• pause — No detail payload. Dispatched when timers become paused.
• resume — No detail payload. Dispatched when timers resume.

Param	Type	Description
[options]	ToastQueueOptions	Queue configuration.

Example

import { ToastQueue } from 'toast-queue';

const toastQueue = new ToastQueue();

toastQueue.add('Changes saved.');

toastQueue.element : HTMLElement

The root <toast-queue> element for this queue instance.

Use this element to apply instance-specific styles or inspect the queue's DOM state.

Kind: instance property of ToastQueue
Read only: true

toastQueue.size : number

The number of toasts currently in the queue.

Kind: instance property of ToastQueue
Read only: true

toastQueue.position : ToastQueuePosition

Gets or sets the queue position.

Supported positions are:

• top-start
• top-center
• top-end
• bottom-start
• bottom-center
• bottom-end

Changing the position updates the queue and existing toasts in place.

Kind: instance property of ToastQueue

toastQueue.visibleLimit : number

Gets or sets the number of toasts considered visible.

Toasts beyond this limit remain rendered and in the queue, but are marked with data-hidden. The number of hidden toasts is exposed through data-hidden-count on the queue element.

CSS presets can use these attributes to create stacked or peek effects.

Kind: instance property of ToastQueue

toastQueue.add(content, [options]) ⇒ ToastRecord

Adds a toast notification to the queue.

Toasts are added immediately. When the visibleLimit is exceeded, additional toasts remain in the queue but are marked hidden until the visible limit allows them to be shown.

Pass a string for a simple message or an object for a title and optional description.

Kind: instance method of ToastQueue
Returns: ToastRecord - The newly created toast record.
Emits: ToastQueue#event:toast-add

Param	Type	Description
content	ToastContent	Toast message content.
[options]	ToastOptions	Per-toast configuration.

Example

toastQueue.add('Changes saved.');

Example

toastQueue.add({
  title: 'Changes saved',
  description: 'Your profile has been updated.',
});

Example

toastQueue.add('File uploaded.', {
  duration: 3000,
  action: {
    label: 'View',
    onClick: (toast) => {
      console.log(toast);
    },
  },
});

toastQueue.get(id) ⇒ ToastRecord | undefined

Retrieves a toast by its identifier.

Kind: instance method of ToastQueue
Returns: ToastRecord | undefined - The matching toast, or undefined when no toast with that identifier exists.

Param	Type	Description
id	string	Toast identifier.

toastQueue.close(id, [reason]) ⇒ void

Closes a toast and removes it from the queue.

Closing a toast also cancels its auto-dismiss timer and updates queue state. If the toast has an onClose callback, it is invoked after the queue has been updated.

Kind: instance method of ToastQueue
Emits: ToastQueue#event:toast-close

Param	Type	Default	Description
id	string		Toast identifier.
[reason]	CloseReason	'manual'	Reason the toast was closed.

toastQueue.clear() ⇒ void

Closes all toasts and clears the queue.

All auto-dismiss timers are cancelled and the queue is reset to its empty state. Individual onClose callbacks are not invoked.

Kind: instance method of ToastQueue

toastQueue.pause() ⇒ void

Manually pauses all toast auto-dismiss timers.

The manual pause remains active until resume is called. Other pause reasons, such as hover or document visibility, are independent.

Kind: instance method of ToastQueue
Emits: ToastQueue#event:pause

toastQueue.resume() ⇒ void

Removes the queue's manual pause.

Auto-dismiss timers remain paused while another pause reason is active, such as hover, focus, or document visibility.

Kind: instance method of ToastQueue
Emits: ToastQueue#event:resume

toastQueue.destroy() ⇒ void

Permanently destroys the queue instance.

Removes the queue element, clears all auto-dismiss timers, removes event listeners, and releases associated resources.

The instance must not be used after calling destroy().

Kind: instance method of ToastQueue

ToastQueueOptions : Object

Configuration options for a ToastQueue.

Kind: global typedef
Properties

Name	Type	Default	Description
[root]	HTMLElement	document.body	Container into which the queue is mounted.
[duration]	number	6000	Default auto-dismiss duration in milliseconds. Use 0 to disable automatic dismissal.
[position]	ToastQueuePosition	'top-end'	Position of the toast queue.
[visibleLimit]	number	3	Number of toasts considered visible at once. Additional toasts remain queued and can be exposed by CSS presets.
[template]	ToastQueueTemplate		Optional HTML templates used to render the queue, toast items, and action buttons.

ToastQueuePosition : 'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end'

Position of the toast queue.

Kind: global typedef

ToastQueueTemplate : Object

HTML templates used to render a toast queue.

Templates are expected to contain the data-part attributes used by the library to locate and update their elements.

Kind: global typedef
Properties

Name	Type	Description
[root]	string	HTML for the queue root and toast group.
[item]	string	HTML for an individual toast item.
[actionButton]	string	HTML for an individual action button.

ToastContent : string | ToastContentObject

Content displayed by a toast.

Kind: global typedef

ToastContentObject : Object

Kind: global typedef
Properties

Name	Type	Description
title	string	Primary toast message.
[description]	string	Optional supporting text displayed below the title.

ToastOptions : Object

Configuration for an individual toast.

Kind: global typedef
Properties

Name	Type	Default	Description
[duration]	number		Auto-dismiss duration in milliseconds. 0 disables automatic dismissal.
[dismissible]	boolean	true	Whether the toast can be manually dismissed.
[priority]	ToastPriority	'normal'	Announcement priority passed to ariaNotify().
[className]	string		Additional CSS class names applied to the toast.
[icon]	string		Trusted HTML markup rendered in the toast's icon slot. Do not pass user-controlled or unsanitized content.
[action]	ToastAction		Optional action button configuration.
[onClose]	ToastCloseHandler		Called after the toast has been closed and removed from the queue.

ToastPriority : 'normal' | 'high'

Toast priority used for screen-reader announcements.

high requests a higher announcement priority from ariaNotify().

Kind: global typedef

ToastAction : Object

Configuration for an optional toast action button.

Kind: global typedef
Properties

Name	Type	Description
label	string	Text displayed in the action button.
[onClick]	ToastActionHandler	Called when the action button is clicked.

ToastActionHandler ⇒ void

Called when a toast action button is clicked.

Kind: global typedef

Param	Type	Description
toast	ToastRecord	The toast associated with the action.

ToastCloseHandler ⇒ void

Called after a toast is closed and removed from the queue.

Kind: global typedef

Param	Type	Description
toast	ToastRecord	The toast that was closed.

ToastRecord : Object

Record representing a toast managed by a ToastQueue.

Kind: global typedef
Properties

Name	Type	Description
id	string	Unique identifier for the toast.
timestamp	number	Creation timestamp in milliseconds.
content	ToastContent	Content displayed by the toast.
[icon]	string	Trusted HTML markup for the toast icon.
[action]	ToastAction	Optional action button configuration.
dismissible	boolean	Whether the toast can be manually dismissed.
priority	ToastPriority	Screen-reader announcement priority.
[className]	string	Additional CSS classes applied to the toast.
[onClose]	ToastCloseHandler	Called after the toast is closed.
[timer]	Timer	Auto-dismiss timer.
itemRef	HTMLLIElement	Associated toast item in the DOM.

CloseReason : 'timeout' | 'button' | 'escape' | 'swipe' | 'manual'

Reason a toast was closed.

Kind: global typedef

ActivationReason : 'focus' | 'click'

Reason the queue becomes interaction-active.

Kind: global typedef

ToastAddEventDetail : Object

Detail payload for the toast-add event.

Kind: global typedef
Properties

Name	Type	Description
toast	ToastRecord	The toast that was added to the queue.

ToastCloseEventDetail : Object

Detail payload for the toast-close event.

Kind: global typedef
Properties

Name	Type	Description
toast	ToastRecord	The toast that was closed.
reason	CloseReason	The reason the toast was closed.

ToastActionEventDetail : Object

Detail payload for the toast-action event.

Kind: global typedef

ToastActivateEventDetail : Object

Detail payload for the activate event.

Kind: global typedef

ToastDeactivateEventDetail : Object

Detail payload for the deactivate event.

Kind: global typedef