kiltoast

kilToast

Neon, AI-feel toast notifications - zero deps, CSS auto-injected, swipe-to-dismiss, progress bar, positions, types, ARIA-friendly.
Solid by default, with optional mode: 'simple' or mode: 'neutral' via kilToast.configure().

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>

React / Next.js

React (Vite / CRA / Next pages router)

import kilToast from 'kiltoast';

export default function SaveButton() {
  return <button onClick={() => kilToast.success('Saved')}>Save</button>;
}

Next.js (App Router)

'use client';
import kilToast from 'kiltoast';

export default function Page() {
  return <button onClick={() => kilToast.info('Welcome')}>Show toast</button>;
}

If you must call it from code that can run on the server, lazy-load it on the client:

useEffect(() => {
  import('kiltoast').then(({ default: kt }) => kt.info('Client only'));
}, []);

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)
• html: string set rich HTML content (if given, message is ignored)
• rtl: boolean right-to-left content (default: false)

ToastHandle:

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

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)

// Without 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'  // Simple toasts
});

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

// 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.configure({ mode: 'neutral' });
kilToast('Neutral info',   { type:'info' });
kilToast('Neutral warn',   { type:'warning' });
kilToast('Neutral error',  { type:'danger' });
kilToast('Neutral success',{ type:'success' });

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 and 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-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;
}

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 for info/succ/warn/dang, --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: use kilToast.configure({ mode: 'neutral' }) for a uniform glass look.
• Simple mode: use kilToast.configure({ mode: 'simple' }) for flat color toasts.

Changelog

• v1.2.0 - Adaptive light/dark solid by default, optional mode: 'neutral', reduced glow/blur, emoji icons.
• v1.1.x - Per-type tinted background mode.
• v1.0.x - Initial public release.

License

MIT (c) Kilvish (Vasu Birla)