popt

Beautiful toast notifications with pill-to-card animations, spring physics, and zero dependencies.

~14 KB JS · ~8 KB CSS · Zero dependencies · TypeScript ready

Install

npm install poptjs

import popt from 'poptjs';
import 'poptjs/dist/popt.css';

Quick Start

// Simple pill notification
popt.success('Event saved!');

// Expanded card with description
popt.error({
  title: 'Payment declined',
  description: 'Card ending in 4242 was declined.'
});

API

Methods

| Method | Description | |--------|-------------| | popt.success(opts) | Green checkmark. Confirmations, saves. | | popt.error(opts) | Red X. Failures, declined payments. | | popt.warning(opts) | Orange alert. Low inventory, expiring sessions. | | popt.info(opts) | Blue info. Updates, announcements. | | popt.action(opts) | Purple arrow. Includes action button. | | popt.show(opts) | Gray default. Custom icon optional. | | popt.promise(promise, handlers) | Loading → success/error transition. | | popt.dismiss() | Dismiss current toast. | | popt.isActive() | Returns true if a toast is visible. | | popt.init(config) | Set global defaults. |

Every method accepts a string (title-only pill) or an options object.

Toast Options

| Property | Type | Description | |----------|------|-------------| | title | string | Text shown in the pill header | | description | string \| HTMLElement | Expanded card body content | | duration | number \| null | Auto-dismiss ms. null = persistent | | button | { title, onClick } | Action button inside card | | icon | string | Custom SVG string for badge | | fill | string | Custom badge/progress color | | position | string | Override position for this toast | | expandDelay | number | Pill → card delay in ms | | onDismiss | () => void | Callback when toast is dismissed |

Positions

top-left · top-center (default) · top-right · bottom-left · bottom-center · bottom-right

Examples

Action Button

popt.action({
  title: 'Booking saved as draft',
  description: 'Resume checkout anytime.',
  button: {
    title: 'Resume checkout',
    onClick: () => window.location = '/checkout'
  }
});

Async Promise

popt.promise(fetch('/api/booking'), {
  loading: 'Processing booking...',
  success: 'Booking confirmed!',
  error: 'Something went wrong'
});

// Dynamic messages
popt.promise(fetch('/api/tickets'), {
  loading: 'Loading...',
  success: (data) => ({
    title: 'Loaded!',
    description: `${data.count} tickets found`
  }),
  error: (err) => ({
    title: 'Failed',
    description: err.message
  })
});

Custom Configuration

popt.init({
  position: 'bottom-right',
  duration: 4000,
  expandDelay: 800
});

Custom Color

popt.show({
  title: 'Custom notification',
  description: 'With a custom color.',
  fill: '#e040fb'
});

Features

• Pill → Card animation — Starts as a compact pill, morphs into an expanded card
• Spring physics — Natural-feeling linear() easing
• One toast at a time — Clean, focused UX
• Pause on hover — Timer pauses when user interacts
• Progress bar — Visual countdown synced with dismiss timer
• Promise support — Loading → success/error transitions
• Action buttons — Interactive CTAs inside cards
• 6 positions — Any corner or center, top/bottom
• Safe area support — Respects mobile notch
• Reduced motion — Respects prefers-reduced-motion
• Accessible — role="status", aria-live="polite"
• Zero dependencies — Vanilla JS, no framework needed
• TypeScript definitions — Full IntelliSense support

Browser Support

All modern browsers (Chrome, Firefox, Safari, Edge). The linear() easing function requires recent browser versions.

License

MIT