@kiorabr/react-toast

A lightweight and optimized React toast notification library with TypeScript support.

Features

• ✅ Multiple toast types: success, error, warn, info
• ✅ Configurable duration: Set custom display time for each toast
• ✅ Flexible positioning: Configure X (left, center, right) and Y (top, bottom) positions
• ✅ Click to dismiss: Users can close toasts by clicking
• ✅ Auto-dismiss: Toasts automatically disappear after the specified duration
• ✅ Lightweight: Minimal bundle size with no external dependencies
• ✅ TypeScript: Full TypeScript support with type definitions
• ✅ Optimized: Uses React hooks and memoization for optimal performance
• ✅ Accessible: Full ARIA support and keyboard navigation
• ✅ Visual timer: Animated progress bar showing remaining time

Installation

npm install @kiorabr/react-toast
# or
yarn add @kiorabr/react-toast
# or
pnpm add @kiorabr/react-toast

Usage

1. Import the CSS (Required)

In your main application file or layout:

import "@kiorabr/react-toast/style.css";

2. Wrap your app with ToastContextProvider

import { ToastContextProvider, Toast } from "@kiorabr/react-toast";

function App() {
  return (
    <ToastContextProvider
      config={{
        positionX: "right", // 'left' | 'center' | 'right'
        positionY: "top", // 'top' | 'bottom'
        duration: 3000, // default duration in milliseconds
      }}
    >
      <Toast />
      {/* Your app components */}
    </ToastContextProvider>
  );
}

3. Use the toast hook in your components

import { useToastContext } from "@kiorabr/react-toast";

function MyComponent() {
  const { showToast } = useToastContext();

  return (
    <div>
      <button onClick={() => showToast("Success!", "success")}>
        Show Success Toast
      </button>

      <button onClick={() => showToast("Error occurred", "error")}>
        Show Error Toast
      </button>

      <button onClick={() => showToast("Warning!", "warn")}>
        Show Warning Toast
      </button>

      <button onClick={() => showToast("Info message", "info")}>
        Show Info Toast
      </button>

      {/* Custom duration (5 seconds) */}
      <button onClick={() => showToast("Custom duration", "info", 5000)}>
        Show Long Toast
      </button>
    </div>
  );
}

API Reference

ToastContextProvider Props

| Prop | Type | Default | Description | | ------------------ | ------------------------------- | --------- | -------------------------------- | | config.positionX | 'left' \| 'center' \| 'right' | 'right' | Horizontal position of toasts | | config.positionY | 'top' \| 'bottom' | 'top' | Vertical position of toasts | | config.duration | number | 3000 | Default duration in milliseconds |

useToastContext Hook

Returns an object with the following properties:

• showToast(message: string, type?: ToastType, duration?: number): Display a toast notification
  • message: The text to display
  • type: Optional toast type ('success', 'error', 'warn', 'info'). Default: 'info'
  • duration: Optional custom duration in milliseconds. Overrides the default config duration
• removeToast(id: string): Manually remove a toast by its ID
• toasts: Array of currently displayed toasts
• config: Current toast configuration

Toast Types

type ToastType = "success" | "error" | "warn" | "info";
type ToastPositionX = "left" | "center" | "right";
type ToastPositionY = "top" | "bottom";

Examples

Different Positions

// Top Right (Default)
<ToastContextProvider config={{ positionX: 'right', positionY: 'top' }}>

// Bottom Center
<ToastContextProvider config={{ positionX: 'center', positionY: 'bottom' }}>

// Top Left
<ToastContextProvider config={{ positionX: 'left', positionY: 'top' }}>

Custom Durations

const { showToast } = useToastContext();

// Quick toast (1 second)
showToast("Quick message", "info", 1000);

// Long toast (10 seconds)
showToast("Important information", "warn", 10000);

// Default duration (from config)
showToast("Normal message", "success");

Accessibility

The library includes full accessibility support:

• ARIA labels for screen readers
• Keyboard navigation (Enter, Space, Escape to dismiss)
• Focus management
• Semantic HTML with proper roles
• Visual timer bar with progress indication

Customization

While the library provides default styling via the included CSS file, you can override styles by targeting the classes:

• .toast-container - Main container
• .toast-item - Individual toast
• .toast-icon - Icon wrapper
• .toast-message - Message text
• .toast-timebar - Progress bar

TypeScript

The library is written in TypeScript and exports all necessary types:

import type {
  ToastType,
  ToastPositionX,
  ToastPositionY,
  ToastConfig,
} from "@kiorabr/react-toast";

Browser Support

Works in all modern browsers that support:

• ES2020
• CSS animations
• CSS transforms

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

Found a bug or have a feature request? Open an issue