toastive

Toastive

👀 Overview

Toastive is a lightweight, accessible, and fully customizable native web component library for creating toast notifications.

Some of the key features include:

• 🪶 Lightweight: ~6 KB gzipped, zero dependencies.
• ♿ Accessible: ARIA roles, keyboard support, focus management, prefers-reduced-motion.
• 🎨 Customizable: 30+ CSS variables to style every detail.
• 🚀 Easy to use: one function call — showToastive(props).
• 📦 Zero dependencies: ESM-only, no runtime deps.
• 🌐 Framework-agnostic: vanilla web component, works with React, Vue, Svelte, Angular.
• ⏸ pauseOnHover: timer pauses on hover/focus.
• 🖐 Drag to dismiss: vertical drag toward the toast's corner.
• 🌈 Themes: 6 variants + light/dark color themes.

📦 Installation

NPM

npm install toastive

Yarn

yarn add toastive

🚀 Usage

Toastive element is, at the end of the day, a web component. So, you can use it like any other web component. However, we also provide a simple API to make it easier to use.

Import the module

import { showToastive } from 'toastive'

showToastive()

The showToastive() method is the simplest way to show a toast notification. It accepts an object with the following properties:

Types

Toastive library is fully developed with TypeScript. So, you can use the types in your project.

import {
  MmToastive,
  ToastiveInstance,
  ToastivePosition,
  ToastiveProps,
  ToastiveTheme,
  ToastiveVariant
} from 'toastive'

Example

import { showToastive, ToastiveProps, ToastivePosition, ToastiveVariant } from 'toastive'

showToastive({
  title: 'Toastive',
  message: '👋 Hi from top-right corner!',
  position: ToastivePosition.TopRight,
  variant: ToastiveVariant.Success,
  autoClose: true,
  duration: 5000,
  closeButton: false
})

Code above will show a toast notification with a success variant, a title, and a message. The toast will be displayed in the top-right corner of the screen and will automatically close after 5 seconds.

Closing a toastive

Toasts are widely used in applications to show notifications to users. However, these notifications should not be blocking the user, so in terms of UX, it is advisable to use the default autoClose property.

However, sometimes you may want to allow the user to close the toast manually. You can do this by setting the closeButton property to true.

showToastive({
  title: 'Toastive',
  message: '👋 Hi from top-right corner!',
  position: ToastivePosition.TopRight,
  variant: ToastiveVariant.Success,
  autoClose: false,
  closeButton: true
})

Additionally, you can close a toastive manually by calling the close() method.

const toast = showToastive({
  title: 'Toastive',
  message: '👋 Hi from top-right corner!',
  position: ToastivePosition.TopRight,
  variant: ToastiveVariant.Success,
  autoClose: false,
  closeButton: true
})

// Do something...
toast.close()

All toast can be closed by dragging them to the right or left side of the screen, depending on the position of the toast. These gestures are enabled by default and it's fully compatible with touch devices. You can disable this feature by setting the draggable property to false.

Accessibility & UX

Toastive ships with sensible accessibility defaults so you don't have to wire them up:

• role / aria-live: success, info and loading toasts are announced politely (role="status" + aria-live="polite"); error and warning toasts are announced assertively (role="alert" + aria-live="assertive").
• aria-atomic="true": screen readers read the whole toast on each update, not just the diff.
• Close button has aria-label="Close notification".
• Keyboard support: each toast is focusable (tabindex="0"); press Tab to reach it and Esc to close it.
• prefers-reduced-motion: CSS animations and the JS exit animation are skipped when the user has the OS preference set.
• pauseOnHover: by default the auto-close timer and progress bar pause while the toast is hovered or focused, and resume when it leaves.

You can disable pauseOnHover per toast:

showToastive({
  message: 'Strict timer',
  pauseOnHover: false
})

Dark mode

Each toast accepts a theme prop:

The theme is per toast — it does not auto-detect from the OS, because the host page may not have its own dark theme implemented. Pass theme: ToastiveTheme.Dark explicitly when you want a dark toast, or set it globally via setDefaults().

showToastive({
  message: 'Always dark',
  theme: ToastiveTheme.Dark
})

Global defaults

Use setDefaults() to apply options to every subsequent showToastive() call. Useful when you want a global position or duration once at startup instead of repeating them.

import { setDefaults, ToastivePosition } from 'toastive'

setDefaults({
  position: ToastivePosition.TopRight,
  duration: 3000
})

setDefaults() also accepts maxVisible, which caps the number of active toasts per position (FIFO eviction):

setDefaults({ maxVisible: 5 })  // each wrapper holds at most 5 toasts

Clearing toasts

Use clearToasts() to remove active toasts. Pass a position to scope the clear, or omit it to remove every active toast.

import { clearToasts, ToastivePosition } from 'toastive'

clearToasts()                              // remove everything
clearToasts(ToastivePosition.TopRight)     // remove only top-right toasts

Updating a toastive

You can update a toastive by calling the update() method. This method accepst same properties as showToastive() method.

const toast = showToastive({
  title: 'Toastive',
  message: '👋 Hi from top-right corner!',
  position: ToastivePosition.TopRight,
  variant: ToastiveVariant.Loading,
  autoClose: false,
  closeButton: true
})

// Do something...
toast.update({
  title: 'Updated title',
  message: 'Updated message',
  variant: ToastiveVariant.Warning,
  autoClose: true
})

Action button

Add a secondary action button (typically used for "Undo", "Retry", "View", etc.):

showToastive({
  message: 'File deleted',
  action: {
    label: 'Undo',
    onClick: () => restoreFile(),
    closeOnClick: true  // default; pass false to keep the toast open
  }
})

Custom content via slots

For full markup control, instantiate MmToastive directly and use the built-in slots (icon, title, message). You can also pass an HTML string for the icon via customIcon:

showToastive({
  message: 'Custom icon',
  customIcon: '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="currentColor"/></svg>'
})

💅 Styling

Toastive is fully customizable. You can easily customize the appearance of the toasts by using next CSS variables.

Wrapper

Font

Colors

Border

Shadow

Layout

Close button

Progress bar

Variants

Example

:root {
  --toastive-wrapper-horizontal-offset: 2rem;
  --toastive-wrapper-vertical-offset: 2rem;
  --toastive-wrapper-gap: 0.5rem;

  --toastive-font-family: 'Arial', sans-serif;
  --toastive-font-size: 1.2rem;

  --toastive-content-color: #ccc;
  --toastive-background-color: #333;
}