kilToast

Neon, AI‑feel toast notifications — zero deps, CSS auto‑injected, swipe‑to‑dismiss, progress bar, positions, types, ARIA‑friendly.
v1.2.0 is adaptive for light & dark UIs: solid, per‑type backgrounds by default and an optional neutral glass look via neutral: true.

Author: Kilvish (Vasu Birla) • License: MIT

Install

npm i kiltoast

CDN / self‑host:

<script src="/node_modules/kiltoast/kiltoast.min.js"></script>
<!-- or your CDN -->
<script src="https://your.cdn/kiltoast.min.js"></script>

kiltoast.min.js attaches a global window.kilToast. No build step or CSS file needed.

Quick Start

<script src="kiltoast.min.js"></script>
<script>
  kilToast('Hello world'); // info • center • 2s • solid (adaptive to light/dark)
</script>

API

kilToast(message, options?) → ToastHandle

Creates a toast.

Options (all optional):

• position: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center" | "center" (default: "center")
• type: "info" | "success" | "warning" | "danger" (default: "info")
• duration: number ms (default: 2000; 0 = sticky)
• close: boolean show close button (default: true)
• pauseOnHover: boolean (default: true)
• clickToClose: boolean (default: true)
• showProgress: boolean (default: true)
• maxStack: number max visible per position (default: 6)
• gap: number px between toasts (default: 10)
• offset: number px from screen edge (default: 16)
• id: string custom id you assign (used to reference this toast later)
• replaceId: string id of an existing toast to replace in‑place
• icon: string|HTMLElement override icon (single char or small HTML). Defaults are emoji: success ✅, info ℹ️, warning ⚠️, danger ⛔.
• html: string set rich HTML content (if given, message is ignored)
• rtl: boolean right‑to‑left content (default: false)
• neutral: boolean NEW — when true, uses the same neutral glass background for every type. Default false (solid per‑type).

ToastHandle:

• .el: HTMLElement root element
• .dismiss(): programmatically close the toast
• .update({ type?, text?, html?, icon?, neutral? }): live‑patch content/type/icon/neutral

Helpers:

kilToast.success(msg, opts?)
kilToast.info(msg, opts?)
kilToast.warning(msg, opts?)
kilToast.danger(msg, opts?)

kilToast.configure(defaults) // set global defaults for future toasts
kilToast.destroyAll()        // remove every toast on the page

Usage Examples

1) Basic

<script>
  kilToast('Order placed — pay later');   // info, center, 2s
</script>

2) With options

kilToast('Saved successfully', {
  type: 'success',
  position: 'top-right',
  duration: 3000,
  close: true
});

3) Type helpers

kilToast.success('Profile updated');
kilToast.warning('Low balance', { position: 'bottom-center' });
kilToast.danger('Payment failed', { duration: 5000 });
kilToast.info('New version available');

4) Replace by id

Replace a running toast (useful for progress → success).

// Start sticky “Uploading…”
kilToast('Uploading…', {
  id: 'up1',
  type: 'info',
  duration: 0,          // sticky
  showProgress: false,
  close: true
});

// Later: replace in-place
setTimeout(() => {
  kilToast('Upload complete', {
    replaceId: 'up1',
    type: 'success',
    duration: 1800
  });
}, 1200);

5) Global defaults ( You can put it in your Common Footer or header Once only )

// wiothout mode: 
kilToast.configure({
  position: 'top-right',
  duration: 2500,
  gap: 12,
  offset: 18
});


// With   mode: 'simple'
kilToast.configure({
  position: 'top-right',
  duration: 3000,
  gap: 12,
  offset: 18,
  mode: 'simple'  // For Simple Toasters  ( I Think Best according to Me )
});


kilToast.configure({
  position: 'top-right',
  duration: 3000,
  gap: 12,
  offset: 18,
  mode: 'neutral'    // for Glass View 
});


// This toast uses the new defaults
kilToast('Defaults applied ✅', { type: 'success' });

6) Programmatic control

const t = kilToast('Syncing…', { duration: 0 }); // sticky

// Update content/type
setTimeout(() => t.update({ type: 'success', text: 'Synced!' }), 800);

// Close when you want
setTimeout(() => t.dismiss(), 1200);

7) HTML content + custom icon

kilToast('', {
  html: '<b>Heads up:</b> Check <a href="/invoices">Invoices</a> for details.',
  icon: '💡',
  type: 'info',
  position: 'bottom-center'
});

8) Neutral glass background (same look for all types)

kilToast('Neutral info',   { type:'info',    neutral:true });
kilToast('Neutral warn',   { type:'warning', neutral:true });
kilToast('Neutral error',  { type:'danger',  neutral:true });
kilToast('Neutral success',{ type:'success', neutral:true });

Accessibility

• Uses role="status" and aria-live="polite" to announce messages non‑intrusively.
• Close button includes aria-label="Close".
• Pause timer on hover avoids timing stress for screen‑magnifier users.

Gestures & Interactions

• Click to close (configurable).
• Swipe/drag to dismiss (touch & mouse).
• Pause on hover (configurable).
• Optional progress bar that counts down the remaining time.

Theming / Styling

All styles are injected once and controlled via CSS variables. The defaults adapt to light and dark via prefers-color-scheme. Override after the script if needed:

:root{
  --kil-toast-radius: 14px;
  --kil-toast-blur: 6px;                 /* neutral mode only */
  --kil-toast-info:   #1d4ed8;
  --kil-toast-succ:   #047857;
  --kil-toast-warn:   #ffb300;           /* keep warning readable on light */
  --kil-toast-dang:   #b91c1c;

  /* Fine‑tune solid palettes (optional) */
  --kil-toast-solid-info-bg:#e6efff;
  --kil-toast-solid-info-fg:#0b3b8f;
  --kil-toast-solid-info-bd:#b8d8ff;
}

Available variables (non‑exhaustive):
--kil-toast-font, --kil-toast-radius, --kil-toast-pad, --kil-toast-gap, --kil-toast-shadow,
--kil-toast-info, --kil-toast-succ, --kil-toast-warn, --kil-toast-dang,
--kil-toast-solid-*-bg|fg|bd for info/succ/warn/dang,
--kil-toast-neutral-bg|fg|bd, --kil-toast-blur,
--kil-toast-glow-info|succ|warn|dang.

Tips

• Sticky toasts: set duration: 0 and show a close button.
• Queues: control stack with maxStack (per position). Oldest auto‑trims beyond the limit.
• Global layout: prefer kilToast.configure({ position: 'top-right' }) once at app start.
• Neutral mode: pass neutral: true for a uniform glass look across types.

Changelog

• v1.2.0 — Adaptive light/dark solid by default, optional neutral glass, reduced glow/blur, emoji icons (✅ ℹ️ ⚠️ ⛔).
• v1.1.x — Per‑type tinted background mode.
• v1.0.x — Initial public release.

License

MIT © Kilvish (Vasu Birla)