better-toast

A lightweight, animated React toast notification library with a dark glassmorphism design — no stylesheet to import.

Features

• 🎨 Dark glassmorphism — frosted glass look with backdrop blur, inspired by iOS & Twitter notifications
• 🔔 Typed toasts — success, error, warning, info, loading, and default — each with a distinct icon badge
• 🌀 Spring physics — powered by Motion with satisfying scale-bounce arrival and smooth stack animations
• 🔊 Sound — optional tap sound on each toast (built-in)
• 🔂 Stacking — up to N toasts stack with parallax peek effect
• ⏱ Progress bar — auto-closing toasts show a live countdown bar
• 💬 Promise API — wraps any Promise with loading → success/error flow
• ✅ Zero CSS imports — styles are injected automatically
• 📦 Tiny — tree-shakeable ESM + CJS, React & React-DOM are peer deps

Install

npm install better-toast
# or
pnpm add better-toast
# or
yarn add better-toast

Peer deps: react >= 18 and react-dom >= 18

Quick start

1. Add <Toaster /> once in your app

// app/layout.tsx (Next.js) or App.tsx (Vite/CRA)
import { Toaster } from 'better-toast';

export default function RootLayout({ children }) {
  return (
    <>
      {children}
      <Toaster position="bottom-right" />
    </>
  );
}

2. Call toast() anywhere

import { toast } from 'better-toast';

toast('Hello world!');
toast.success('Saved successfully!');
toast.error('Something went wrong.');
toast.warning('Disk space is low.');
toast.info('A new version is available.');

// Loading — persists until you dismiss it
const id = toast.loading('Uploading…');
toast.dismiss(id);

// Promise helper
toast.promise(uploadFile(), {
  loading: 'Uploading…',
  success: 'File uploaded!',
  error: (err) => `Upload failed: ${err.message}`,
});

API

toast(message, options?)

| Option | Type | Default | Description | |---|---|---|---| | duration | number | 4000 | Auto-close delay in ms. Use Infinity to persist. | | position | ToastPosition | 'bottom-right' | Where the toast appears. | | type | ToastType | 'default' | Controls the icon badge colour. | | description | string | — | Secondary text below the message. | | icon | ReactNode | — | Custom icon inside the circle (overrides default). | | action | ToastAction | — | Action button { label, onClick }. | | id | string | auto | Use to update an existing toast. | | onDismiss | (id) => void | — | Called when the toast is manually dismissed. | | onAutoClose | (id) => void | — | Called when the toast auto-expires. | | className | string | — | Extra class on the toast element. | | style | CSSProperties | — | Inline styles on the toast element. |

toast.success / error / warning / info / loading

Same signature as toast() — shorthand methods that set type automatically.

toast.promise(promise, messages, options?)

toast.promise(myPromise, {
  loading: 'Loading…',
  success: (data) => `Done! Got ${data.count} items.`,
  error:   (err)  => `Error: ${err.message}`,
});

toast.dismiss(id) / toast.dismissAll()

Programmatically dismiss one or all toasts.

toast.update(id, message, options?)

Update an existing toast in place (or create a new one if the id is gone).

<Toaster /> props

| Prop | Type | Default | Description | |---|---|---|---| | position | ToastPosition | 'bottom-right' | Default position for all toasts. | | duration | number | 4000 | Default auto-close duration. | | visibleToasts | number | 5 | Max toasts shown at once. | | pauseOnHover | boolean | true | Pause countdown when hovering. | | closeButton | boolean | false | Show an × close button on each toast. | | className | string | — | Extra class on the container. | | style | CSSProperties | — | Inline styles on the container. |

ToastPosition

'top-left' | 'top-center' | 'top-right'
'bottom-left' | 'bottom-center' | 'bottom-right'

Customising icons

Pass any ReactNode as icon to replace the default circle content:

toast.success('Profile updated!', {
  icon: <img src="/avatar.png" style={{ width: 42, height: 42, borderRadius: '50%' }} />,
});

The type badge (colour dot) still shows in the corner based on the type.

Custom CSS variables

Override these in your own stylesheet to retheme the toasts:

:root {
  --bt-bg:            rgba(28, 28, 30, 0.72); /* Toast background */
  --bt-fg:            #f2f2f7;                /* Primary text */
  --bt-desc-fg:       rgba(235, 235, 245, 0.58); /* Description text */
  --bt-radius:        20px;                   /* Border radius */
  --bt-shadow:        0 12px 40px rgba(0,0,0,.55), 0 2px 10px rgba(0,0,0,.35);
  --bt-offset:        24px;                   /* Viewport edge offset */
  --bt-z-index:       9999;

  /* Icon badge accent colours */
  --bt-success-accent: #30d158;
  --bt-error-accent:   #ff453a;
  --bt-warning-accent: #ffd60a;
  --bt-info-accent:    #0a84ff;
}

License

MIT © abheeee03