ToastaX

3.0.0 • Public • Published by Mahmud

JS♡TS npm

ToastaX 3.0

ToastaX is a modern, customizable, and accessible toast notification library for React applications. It provides a flexible, promise-based API for displaying notifications with rich themes, animations, sizes, shapes, and interactive features. Optimized for performance and accessibility, ToastaX supports progress bars, swipe-to-dismiss, custom styling, toast clustering, and responsive design, making it ideal for modern web applications.

Installation

Install ToastaX via npm or yarn:

npm install toastax

Install DOMPurify as a peer dependency for HTML sanitization:

npm install dompurify

Usage

Basic Setup

Import ToastaX and the Toaster component, then render the toaster in your React app:

import { Toaster, toastax } from 'toastax';
import 'toastax/dist/toastax.css';

function App() {
  return (
    <div>
      & Wildcard to avoid HTML encoding issues
      <Toaster position="top-right" theme="light" />
      <button
        onClick={() =>
          toastax.success('Operation completed!', {
            duration: 3000,
            size: 'md',
            shape: 'rounded',
            animation: 'bounce',
          })
        }
      >
        Show Toast
      </button>
    </div>
  );
}

export default App;

Custom ToastaX Instance

Create a custom instance with default options for consistent styling:

import { Toaster, ToastaX } from 'toastax';
import 'toastax/dist/toastax.css';

const toast = new ToastaX({
  position: 'bottom-right',
  theme: 'gradient-blue',
  duration: 5000,
  size: 'lg',
  shape: 'pill',
  opacity: 90,
  progressPosition: 'top',
  progressHeight: 'thick',
  pauseOnHover: true,
  closable: true,
  swipeToDismiss: true,
  userCustom: {
    '--user-border-radius': '16px',
  },
});

function App() {
  return (
    <div>
      <Toaster toastaxInstance={toast} />
      <button
        onClick={() =>
          toast.info('Info message', {
            title: 'Info',
            actions: [{ label: 'Retry', onClick: () => console.log('Retried') }],
          })
        }
      >
        Show Info Toast
      </button>
    </div>
  );
}

export default App;

Promise-Based Toasts

Handle asynchronous operations with a promise-based API:

import { toastax } from 'toastax';

toastax.promise(
  fetch('https://api.example.com/data'),
  {
    loading: 'Fetching data...',
    success: (data) => ({
      message: `Loaded ${data.length} items!`,
      theme: 'glass',
      size: 'xl',
      opacity: 80,
      customIcon: <svg>{/* Custom SVG */}</svg>,
    }),
    error: (err) => `Failed: ${err.message}`,
    description: (data) => data.message || 'Operation completed',
    progressPosition: 'top',
    progressHeight: 'thick',
  }
);

Custom JSX Toasts

Render custom React components as toasts:

import { toastax } from 'toastax';

toastax.custom(
  (id) => (
    <div className="flex flex-col gap-2">
      <h3 className="font-bold">Custom Toast</h3>
      <p>This is a custom JSX toast!</p>
      <button
        className="bg-blue-500 text-white px-4 py-1 rounded"
        onClick={() => toastax.dismiss(id)}
      >
        Close
      </button>
    </div>
  ),
  { duration: 5000, position: 'top-center', theme: 'minimal' }
);

Custom Styling

Apply custom colors or CSS variables for tailored appearances:

import { toastax } from 'toastax';

toastax.success('Custom styled toast', {
  customColor: '#ff6f61',
  size: 'sm',
  shape: 'square',
  userCustom: {
    '--user-bg': 'rgba(200, 100, 50, 0.8)',
    '--user-color': '#ffffff',
    '--user-border-radius': '20px',
    '--user-shadow': '0 4px 12px rgba(0, 0, 0, 0.3)',
  },
});

Configuration Options

Customize ToastaX with these options to tailor toast behavior and appearance.

Option Type Default Description

API Methods

Manage toasts with these robust API methods.

Method Signature Description

For Clear Docs Visit: npmjs

Styling

Customize ToastaX using CSS custom properties defined in toastax.css:

:root {
  --toastax-border-radius: 8px;
  --toastax-shadow: 0 8px 16px rgba(0, 0, 0, 0.2);
  --toastax-font-size: 1rem;
  --toastax-progress-color: #4CAF50;
  --toastax-gap: 16px;
}

Override styles for specific themes or apply custom styles via the userCustom option:

toastax.success('Styled toast', {
  userCustom: {
    '--user-bg': 'linear-gradient(135deg, #ff6f61, #de3c9a)',
    '--user-color': '#ffffff',
    '--user-border-radius': '16px',
    '--user-shadow': '0 4px 12px rgba(0, 0, 0, 0.3)',
  },
});

For advanced customization, target specific elements with [data-toastax-toast][data-theme="..."] or [data-toastax-toast][data-type="..."] selectors.

Accessibility

Plugins

Extend ToastaX with plugins for additional functionality:

Example plugin registration:

import { ToastaX } from 'toastax';

const toast = new ToastaX();
toast.registerPlugin('sound', {
  init: (toastax) => console.log('Sound plugin initialized'),
  show: ({ id, toast }) => new Audio('/path/to/sound.mp3').play(),
});

TypeScript Support

ToastaX is fully typed for a robust developer experience. Import types to leverage IntelliSense and type safety:

import { Toaster, toastax, ToastOptions } from 'toastax';

const options: Partial<ToastOptions> = {
  theme: 'gradient-purple',
  size: 'lg',
  shape: 'pill',
  animation: 'zoom',
  userCustom: {
    '--user-bg': 'linear-gradient(135deg, #667eea, #764ba2)',
  },
};

toastax.success('Typed success!', options);

See index.d.ts for complete type definitions.

Performance