🌟 Overview

TikTiktoast is a Dynamic Island–style toast/notification library for web applications.
It is lightweight (~5KB gzipped), zero dependencies, accessible, and SSR-safe, built with Vanilla JS + TypeScript + Web Animations API.

Perfect for vanilla JavaScript, TypeScript, React, Next.js, Nuxt, or any modern framework.

✨ Features

• 🏝️ Dynamic Island morphing — Pill-to-card transitions with spring easing
• 📚 Stacking & queue — Max 5 visible, rest queued with animated reflow
• 🔄 Promise tracking — loading → success/error transitions in one API call
• 🔁 Deduplication — Same id updates toast in place with morph animation
• 📊 Progress bar — 2px WAAPI-animated countdown bar
• 👆 Swipe to dismiss — Rubber-band gesture (lazy-loaded module)
• 🌐 RTL support — Auto-detected, flips icons, text, and swipe direction
• ♿ Accessible — role="alert", aria-live, keyboard navigation, Alt+T focus
• 🖥️ SSR safe — No window/document access at import time
• 🎯 Zero dependencies — Pure Vanilla JS + TypeScript + Web Animations API
• 🎬 Reduced motion — Respects prefers-reduced-motion: reduce
• 🎨 Customizable — CSS variables, custom icons, custom renderers

📦 Installation

npm install tiktiktoast

yarn add tiktiktoast

pnpm add tiktiktoast

CDN (No bundler)

<script src="https://unpkg.com/tiktiktoast/dist/tiktik.umd.js"></script>
<script>
  Tiktik.success('Hello from CDN!')
</script>

🚀 Quick Start

import { Tiktik } from 'tiktiktoast'

// One line. That's it.
Tiktik.success('Changes saved!')
Tiktik.error('Something went wrong.')
Tiktik.warning('Disk space running low.')
Tiktik.info('New update available.')

📖 API

Type Shortcuts

Tiktik.success(message, options?)  // ✓ green accent
Tiktik.error(message, options?)    // ✕ red accent
Tiktik.info(message, options?)     // ℹ blue accent
Tiktik.warning(message, options?)  // ⚠ orange accent

Tiktik.showToast(options)

Tiktik.showToast({
  message: 'Hello world',
  type: 'success',        // 'success' | 'error' | 'info' | 'warning'
  duration: 3000,         // ms, default: 3000. Use Infinity for persistent
  position: 'top',        // 'top' | 'bottom'
  icon: '<svg>...</svg>', // custom SVG string or SVGElement
  progress: true,         // show countdown progress bar
  id: 'unique-key',       // dedup key — same id updates in place
  onClick: () => {},
  onDismiss: () => {}
})

Tiktik.promise(promise, options)

Tiktik.promise(fetch('/api/save'), {
  loading: 'Saving...',
  success: (data) => `Saved! ${data.name}`,
  error:   (err) => `Failed: ${err.message}`,
  duration: 3000,
})

Tiktik.dismiss(id?)

const id = Tiktik.success('Dismissible')
Tiktik.dismiss(id)   // dismiss one
Tiktik.dismiss()     // dismiss all

Tiktik.configure(defaults)

Tiktik.configure({
  type: 'info',
  duration: 5000,
  position: 'bottom',
  progress: true,
})

Tiktik.onStackChange(listener)

Tiktik.onStackChange((visible, queued) => {
  console.log(`Visible: ${visible}, Queued: ${queued}`)
})

🎨 CSS Customization

Override CSS variables on :root:

:root {
  --tiktik-bg: #1a1a2e;
  --tiktik-text: #ffffff;
  --tiktik-radius-pill: 9999px;
  --tiktik-radius-card: 24px;
  --tiktik-shadow: 0 4px 16px rgba(0,0,0,0.3);
  --tiktik-z-index: 999999;
  --tiktik-font-size: 14px;
  --tiktik-duration: 320ms;
}

📏 Bundle Size

| Chunk | Size (gzip) | | --------------- | ----------- | | Base | ~5 KB | | Gestures (lazy) | ~0.75 KB | | Promise (lazy) | ~0.5 KB |

Gesture and promise modules are lazy-loaded. Initial bundle stays lean.

🌐 Browser Support

All modern browsers with Web Animations API support:

| Chrome | Firefox | Safari | Edge | | ------ | ------- | ------ | ---- | | 36+ | 48+ | 13.1+ | 79+ |

🤝 Contributing

Contributions welcome! Open an issue or submit a pull request.

📄 License

MIT — Free for personal and commercial use.

📌 Links

• NPM: https://www.npmjs.com/package/tiktiktoast
• Homepage / Live Demo: https://tiktiktoast.vercel.app
• Documentation: https://tiktiktoast.vercel.app/docs
• Repository: https://github.com/ianpurifying/Tiktik