# NextToast

NextToast is a lightweight, production-ready toast notification system for React and Next.js applications. Designed with developer experience in mind, it offers a simple global API, full TypeScript support.

---

## Overview

NextToast provides a complete solution for user notifications in modern React applications. It supports standard notifications, asynchronous operations, confirmation dialogs, and fully custom React components. The library is optimized for the Next.js App Router while maintaining compatibility with all React frameworks.

**Key Characteristics:**
- Full TypeScript support
- Next.js App Router compatible
- Client-side safe
- Accessible by default

---

## Features

- **Framework Agnostic Core**: Works seamlessly with Next.js App Router, Pages Router, and standard React applications
- **Global API**: Simple, intuitive methods (`toast.success`, `toast.error`, `toast.info`, `toast.loading`)
- **Flexible Styling**: Toggle between rich semantic colors and minimal plain styling
- **Interactive Patterns**: Built-in support for confirmations, promises, and action buttons
- **ReactNode Support**: Accepts any valid React content, not limited to strings
- **Smart Dismissal**: Configurable auto-dismiss, manual close, and hover-to-pause behavior
- **Stacking Management**: Automatic queue management with configurable limits
- **Accessibility**: Full ARIA support, keyboard navigation, and screen reader optimization

---

## Installation

Install NextToast via your preferred package manager:

```bash
npm install next-toast

yarn add next-toast

pnpm add next-toast

Or copy the source files directly into your project:

src/
├── next-toast.tsx
├── toast-store.ts
└── styles.css
└── styles.ts

Quick Start

1. Mount the Toast Container

Add the NextToast component to your root layout:

import { NextToast } from "next-toast";

export default function RootLayout({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  return (
    <>
      {children}
      <NextToast 
        position="top-center"
        richColors={true}
        closeButton={true}
      />
    </>
  );
}

2. Trigger Notifications

Import the toast store and call methods from anywhere in your application:

import { toast } from "next-toast";

// Basic notifications
toast.success("Changes saved successfully");
toast.error("Failed to save changes");
toast.info("New update available");
toast.warning("Unsaved changes detected");

// With description
toast.success("Profile updated", {
  description: "Your changes have been saved to the server"
});

API Reference

Toast Methods

| Method | Description | |--------|-------------| | toast.success(message, options?) | Success state notification | | toast.error(message, options?) | Error state notification | | toast.info(message, options?) | Informational notification | | toast.warning(message, options?) | Warning notification | | toast.loading(message, options?) | Loading state notification | | toast.custom(render, options?) | Fully custom notification | | toast.promise(promise, messages, options?) | Promise-based notification | | toast.confirm(message, onConfirm, options?) | Confirmation dialog | | toast.update(id, patch) | Update existing notification | | toast.dismiss(id?) | Dismiss notification(s) |

Toast Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | description | ReactNode | undefined | Secondary text content | | duration | number | 4000 | Display duration in milliseconds (Infinity for persistent) | | dismissible | boolean | true | Allow manual dismissal | | action | { label, onClick } | undefined | Action button configuration |

Usage Patterns

Rich vs Plain Styling

Control the visual presentation globally:

<NextToast richColors={true} />  // Semantic background colors
<NextToast richColors={false} /> // Minimal white background

Close Button Configuration

Global setting:

<NextToast closeButton={true} />

Per-toast override:

toast.info("Persistent notification", { 
  dismissible: false,
  duration: Infinity 
});

Confirmation Dialogs

Supports complex React content:

toast.confirm(
  <div>
    <strong>Delete Account</strong>
    <p>This action cannot be undone. All data will be permanently removed.</p>
  </div>,
  () => {
    // Confirm callback
    deleteAccount();
    toast.success("Account deleted");
  },
  {
    label: "Delete",
    cancelLabel: "Keep Account",
    duration: Infinity
  }
);

Promise Handling

Automatic state transitions for async operations:

const saveData = async () => {
  const response = await fetch('/api/save', {
    method: 'POST',
    body: JSON.stringify(data)
  });
  
  if (!response.ok) throw new Error('Save failed');
  return response.json();
};

toast.promise(saveData(), {
  loading: "Saving changes...",
  success: "Changes saved",
  error: "Failed to save"
}, {
  successDescription: "Your profile has been updated",
  errorDescription: "Please check your connection and try again"
});

Custom Components

Render any React content:

toast.custom((t) => (
  <div className="custom-toast">
    <div className="avatar">
      <img src="/user.jpg" alt="User" />
    </div>
    <div className="content">
      <strong>New Follower</strong>
      <span>Jane Smith started following you</span>
    </div>
    <button onClick={() => toast.dismiss(t.id)}>
      Dismiss
    </button>
  </div>
), { duration: 5000 });

Configuration

NextToast Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | position | Position | "top-center" | Container position | | richColors | boolean | true | Enable semantic colors | | closeButton | boolean | true | Show close buttons | | maxVisible | number | 4 | Maximum simultaneous toasts |

Position Values

• top-left
• top-center
• top-right
• bottom-left
• bottom-center
• bottom-right

Accessibility

NextToast implements accessibility best practices:

• ARIA Roles: Error toasts use role="alert" for immediate announcement
• Live Regions: Status updates are announced to screen readers
• Keyboard Navigation: Full keyboard support for all interactions
• Focus Management: Proper focus handling for action buttons
• Color Contrast: WCAG 2.1 AA compliant color combinations

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Requires React 18+ and Next.js 13+ (App Router) or compatible React environment.

TypeScript

Full TypeScript definitions included:

import { toast, type ToastT, type ToastConfig } from "next-toast";

// Custom toast type
const customToast: ToastT = {
  id: "unique-id",
  type: "success",
  message: "Operation completed",
  duration: 4000
};

Project Structure

next-toast/
├── src/
│   ├── next-toast.tsx      # Toast container component
│   
├── toast-store.ts 
├── styles.ts
│── styles.css          # Default styling
├── index.ts                # Public exports
├── package.json
└── README.md

Contributing

Contributions are welcome. Please follow the existing code style and include appropriate tests for new features.

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

MIT License

Copyright (c) 2026 rimu-7

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgments

Built with modern web standards and inspired by the React community's best practices for notification systems.