Skip to content

Notifications ​

The built-in toast engine and confirm dialog. SweetAlert2 and push delivery are not vendored.

Component-level documentation is in Feedback & Overlays. This page covers the engine and the delivery layer.


The toast engine ​

AdminVora ships its own toast implementation — no vendor.

js
AdminVora.toast.success('Order saved');
AdminVora.toast.error('Could not save order');      // type 'danger'
AdminVora.toast.warning('Stock is low');
AdminVora.toast.info('Report is generating');

AdminVora.toast.show({
  type: 'success',                 // success | danger | warning | info
  title: 'Order archived',
  message: 'Order #1042 moved to archive.',
  duration: 8000,                  // ms; 0 = stays until dismissed
  dismissible: true,
  action: { label: 'Undo', run: () => restore(1042) }
});

AdminVora.toast.dismissAll();

show() returns the toast's id and emits av:toast:show; dismissal emits av:toast:hide. From markup, data-av-toast="success" with data-av-toast-title and data-av-toast-message raises one on click.

Rules enforced by the engine ​

RuleImplementation
Max 4 visibleThe oldest leaves when a fifth arrives
Duplicates collapseA counter on the existing toast instead of a second one; pass dedupe: false to opt out
Timers pause on hover and focusWCAG 2.2.1
Toasts with an action get at least 8 sAn action with no label is dropped rather than rendered nameless
danger goes to an assertive regionEverything else is polite
Title and message are escapedRaw input is never parsed as HTML

Confirm dialogs ​

AdminVora.confirm() opens a native <dialog> with a focus trap, Escape, page inerting and focus restore — see Feedback & Overlays. SweetAlert2 is not vendored; if you need input prompts or queues, add it yourself and theme it by reading the --av-* custom properties.


Real-time delivery ​

The runtime has no stream module and opens no connections. Connect from your own code and raise a toast when something arrives. Server-Sent Events are the simplest fit for one-way notifications — the browser reconnects on its own:

js
const es = new EventSource('/notifications/stream', { withCredentials: true });

es.addEventListener('notification', (e) => {
  const n = JSON.parse(e.data);
  AdminVora.toast.info(n.title);
});

Important — behind nginx, send X-Accel-Buffering: no, and write a keepalive comment (: keepalive) every few seconds. Without both, SSE works in development and fails silently in production.

If you poll instead, skip the request while document.hidden is true: a dashboard left open in a background tab overnight otherwise makes hundreds of pointless requests.

Ask for desktop-notification permission only from a user gesture, such as a settings toggle — asking on page load is the fastest way to get permanently blocked.


Notification centre ​

Markup is in Topbar. Rules worth keeping when you wire it to real data:

RuleReason
Unread visually distinct and announcedColour alone is not information
"Mark all read" is a single actionNot a per-item chore
Relative times auto-updatedata-av-relative-time
Empty state present"You are all caught up"
Text from users inserted with textContentIt is user-generated

Toast options ​

OptionDefaultDescription
type'info'success · danger · warning · info
title—Optional heading
message—Body text
duration5000ms; 8000 minimum with an action; 0 persists
dismissibletrueShows a close button
action—{ label, run }
dedupetrueCollapse identical toasts into one with a counter

Events ​

EventDetail
av:toast:show{ id, type, message }
av:toast:hide{ id }

Checklist ​

  • [ ] Toast region is a labelled live region; errors use a separate assertive region
  • [ ] Timers pause on hover and focus
  • [ ] Toasts with actions last ≥ 8 s or persist
  • [ ] Duplicates collapse with a counter
  • [ ] User-supplied notification text inserted with textContent
  • [ ] SSE endpoint sends keepalives and disables proxy buffering
  • [ ] Polling is skipped when the tab is hidden
  • [ ] Desktop permission requested from a user gesture, never on load
  • [ ] Critical information never lives only in a toast

Read next: Animation.

Documentation for @creativeigniter/adminvora