@arxdn/toast

v1.1.1 MIT 0 deps

Lightweight, customizable toast notification system for JavaScript. Zero dependencies, fully typed, with 6 positions, 5 types, pause-on-hover, progress bars, and custom styling.

5 toast types with icons 6 screen positions Pause on hover Progress bar animation Custom CSS classes Zero dependencies Full TypeScript support Accessible (ARIA)

Install @arxdn/toast

$ npm install @arxdn/toast

Quick Start

Basic usage

import { toast } from '@arxdn/toast'

toast.success('Changes saved')
toast.error('Something went wrong')
toast.warning('Low disk space')
toast.info('New update available')

With options

toast.success('Profile updated', {
  duration: 5000,
  position: 'bottom-center',
  pauseOnHover: true
})

Programmatic control

const id = toast.info('Uploading...', { duration: 0 })

// Later...
toast.update(id, 'Upload complete!')
toast.dismiss(id)

Interactive Playground

CONTROLS

0 (persistent)10s

STYLING

PREVIEW

success
top-right

CODE

import { toast } from '@arxdn/toast'

toast.success('Hello from ARXDN!')

Features

Multiple Toast Types

Success, error, warning, info, and default types. Each comes with a distinct icon to match the context of user feedback.

Flexible Positioning

Place toasts in any of six screen positions. Top or bottom, left, center, or right. Toasts stack automatically without overlapping.

Pause on Hover

Hovering a toast pauses its auto-dismiss timer, giving users time to read longer messages without rushing.

Progress Bar

A visual countdown shows remaining time before auto-dismiss. Users always know how long a toast will stay.

Custom Styling

Pass CSS classes to any toast via the className option. Full control over appearance without overriding defaults globally.

Fully Typed

Complete TypeScript definitions for every method, option, and return type. Autocomplete and type-checking work out of the box.

Framework Agnostic

Pure vanilla JavaScript with no framework dependencies. Works with React, Vue, Svelte, Angular, or plain HTML.

Programmatic Control

Create, update, dismiss, and query toasts via a simple API. Build complex notification flows with full lifecycle control.

Why @arxdn/toast

  • Zero dependencies — Nothing extra to install. The entire library is self-contained with no transitive dependencies to audit or update.
  • Lightweight — Minimal footprint. Ships both ESM and CJS builds so bundlers can tree-shake effectively.
  • SSR Safe — Guards all browser API access behind environment checks. No window or document errors during server-side rendering.
  • Simple API — One import, one function call. No providers, no context, no configuration files. Works immediately after install.

API Reference

Method Description
toast.success(message, options?) Show a success toast with a checkmark icon
toast.error(message, options?) Show an error toast with an X icon
toast.warning(message, options?) Show a warning toast with a caution icon
toast.info(message, options?) Show an info toast with an info icon
toast.default(message, options?) Show a plain toast without a type icon
toast.create(message, options) Create a toast with full options control
toast.dismiss(id) Dismiss a specific toast by ID
toast.dismissAll() Dismiss all active toasts
toast.update(id, message, options?) Update an existing toast message and options
toast.getAll() Get an array of all active toast instances

Configuration Options

Option Type Default Description
type 'success' | 'error' | 'warning' | 'info' | 'default' 'default' Visual style and icon of the toast
position 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' 'top-right' Screen position of the toast container
duration number 3000 Auto-dismiss time in milliseconds. 0 for persistent
dismissible boolean true Show close button on the toast
pauseOnHover boolean true Pause auto-dismiss timer when hovering
className string '' Custom CSS class(es) to apply to the toast
icon string '' Custom icon HTML to override the default
onDismiss (instance) => void null Callback fired when the toast is dismissed