Toast

Fully programmatic toast notifications — no HTML needed. Toasts are created and injected into the DOM at runtime via the WojoToast static API. Seven position presets, four type shorthands, an optional countdown progress bar, and configurable animations.

Types

Four shorthand methods for common notification types, plus a neutral show() with no type set.

Type Shorthands

Each shorthand sets the icon, color, and role automatically. By default, the previous toast is dismissed before the new one appears.

import { WojoToast } from './src/js/components/wf-toast.js'

WojoToast.success('Changes saved successfully.')
WojoToast.error('Something went wrong.')
WojoToast.warning('Storage is almost full.')
WojoToast.info('A new version is available.')

// Neutral — no type, no icon
WojoToast.show({ text: 'Your file was uploaded.' })

With Title

Add a bold heading above the body text with the title option. All type shorthands accept an option second argument.

Title via show()

Pass title in the option’s object to add a heading above the body.

WojoToast.show({
  title: 'Upload complete',
  text:  'Your file has been uploaded successfully.',
  type:  'positive',
})

// Shorthand with title in options
WojoToast.error('Please check your connection.', {
  title: 'Connection failed',
})

Dynamic update

Call item.update() to change the text or title while the toast is still visible.

const item = WojoToast.show({
  title: 'Uploading…',
  text:  '0 of 3 files done.',
  type:  'info',
  duration: false,  // sticky while we update it
})

// Later — update in place without closing
setTimeout(() => {
  item.update({ title: 'Done!', text: '3 of 3 files uploaded.' })
}, 2000)

Positions

Seven position presets. The default is top-right . Position demos use exclusive: false so toasts stack per-position.

All Positions

Each container is created lazily the first time a toast targets that position.

WojoToast.show({ text: 'Top right.',     position: 'top-right' })     // default
WojoToast.show({ text: 'Top left.',      position: 'top-left' })
WojoToast.show({ text: 'Top center.',    position: 'top-center' })
WojoToast.show({ text: 'Bottom right.',  position: 'bottom-right' })
WojoToast.show({ text: 'Bottom left.',   position: 'bottom-left' })
WojoToast.show({ text: 'Bottom center.', position: 'bottom-center' })
WojoToast.show({ text: 'Mid center.',    position: 'mid-center' })

Options

Control duration, progress bar, close button, icons, and stacking behavior.

Sticky duration: false

The toast stays until the user closes it or item.close() is called. No progress bar is rendered.

// Stays until manually closed
WojoToast.show({
  text:     'Action required — please review your account.',
  type:     'alert',
  duration: false,
})

No Progress Bar, No Close Button

Toggle the countdown bar with progress: false . Remove the close button with closable: false .

// No countdown bar
WojoToast.info('Sync complete.', { progress: false })

// No close button
WojoToast.show({
  text:     'Processing…',
  type:     'info',
  closable: false,
  duration: 3000,
})

No Icon icon: false

Suppress the leading icon entirely. Also accepts an HTML string to provide a custom icon.

// Suppress icon
WojoToast.success('Profile updated.', { icon: false })

// Custom icon HTML
WojoToast.show({
  text: 'New message received.',
  type: 'info',
  icon: '<i class="icon mail" aria-hidden="true"></i>',
})

Custom Duration

Set duration in milliseconds. Default is 6000 ms. Override globally with WojoToast.setDefaults() .

WojoToast.show({ text: 'Quick — 2 s.', duration: 2000 })
WojoToast.show({ text: 'Default — 6 s.' })
WojoToast.show({ text: 'Slow — 12 s.', duration: 12000 })

// Change the default for all future toasts
WojoToast.setDefaults({ duration: 4000, position: 'bottom-right' })

Options Reference

Option	Type	Default	Description
text	string	''	Body text. HTML is supported.
title	string	''	Bold heading above the body. Optional.
type	string	''	'positive' \| 'negative' \| 'alert' \| 'info' \| 'primary' \| 'secondary' \| '' (neutral). Sets icon, color, and ARIA role.
icon	string \| false \| null	null	null = auto-select by type. false = no icon. HTML string = custom icon markup.
position	string	'top-right'	Container position. One of the seven position presets.
duration	number \| false	6000	Auto-close delay in ms. false = sticky — never auto-closes.
progress	boolean	true	Show a countdown bar while auto-close counts down. Ignored when duration is false.
closable	boolean	true	Show a close (×) button.
exclusive	boolean	true	Dismiss all other visible toasts before showing this one.
stack	number \| false	5	Max visible toasts per container. Oldest is closed when the limit is exceeded. false = unlimited.
animationIn / animationOut	string \| null	null	Override the enter/exit animation. Accepts a wf-ani-* class name or bare keyframe name. null = auto by position.
animDuration	number	400	Enter/exit animation duration in ms.
onClick	Function(item)	null	Called when the toast body is clicked (not the close button).
onShow	Function(item)	null	Called after the enter animation completes.
onHide	Function(item)	null	Called as the exit animation starts.

Events & Public API

Events

Dispatched on the toast element and bubble to document .

Event	detail	Description
wf:toast-show	{ item }	Fired after the enter animation finishes. detail.item is the WojoToastItem instance.
wf:toast-hide	{ item }	Fired as the exit animation starts.

import { WojoToast } from './src/js/components/wf-toast.js'

// Static API
WojoToast.show(options)         // → WojoToastItem
WojoToast.success(text, opts?)  // → WojoToastItem   shorthand
WojoToast.error(text, opts?)    // → WojoToastItem
WojoToast.warning(text, opts?)  // → WojoToastItem
WojoToast.info(text, opts?)     // → WojoToastItem
WojoToast.clear(position?)      // Dismiss all (or all in one position)
WojoToast.setDefaults(opts)     // Override global defaults permanently

// Instance methods (returned by show / shorthands)
const item = WojoToast.success('Saved.')
item.close()                    // Animate-out and remove
item.update({ text?, title? })  // Update content while visible

// DOM events
document.addEventListener('wf:toast-show', e => {
    console.log('Toast shown:', e.detail.item)
})

document.addEventListener('wf:toast-hide', e => {
    console.log('Toast closing:', e.detail.item)
})

// Callbacks
WojoToast.show({
  text: 'Click me!',
  type: 'info',
  onClick:  item => console.log('Clicked', item),
  onShow:   item => console.log('Appeared', item),
  onHide:   item => console.log('Leaving', item),
})

Class Reference

All modifier classes available on .wf-toast

Class	Type	Description
wf-toast	Container	Toast container. Created and positioned by JS. One container per position. Has role="region" for accessibility.
wf-toast-top-right / -top-left / -top-center / -bottom-right / -bottom-left / -bottom-center / -mid-center	Position	Position modifier applied to the container. Controlled by the position option.
wf-toast-item	Item	Each toast notification. Injected by JS. Combined with wf-message-{type} for color theming.
wf-toast-progress / wf-toast-progress-bar	Child	Countdown progress bar injected at the bottom of each toast item. Animated with wf-toast-countdown keyframe.