React Custom Toaster

React Custom Toaster is a highly customizable toast notification component for React applications. It provides an elegant and flexible way to display notifications in your app.

Installation

To install the package, run the following command:

npm install react-custom-toaster

or if you're using yarn:

yarn add react-custom-toaster

Usage

1. Provider Setup

First, wrap your application with the ToastProvider. Typically, this is done in your root component or in _app.js if you're using Next.js:

import { ToastProvider } from 'react-custom-toaster';

function MyApp({ Component, pageProps }) {
  return (
    <ToastProvider>
      <Component {...pageProps} />
    </ToastProvider>
  );
}

export default MyApp;

2. Using the Toaster

Add the Toaster component to your application, usually at the end of your root component:

import { Toaster } from 'react-custom-toaster';

function MyApp({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Toaster />
    </>
  );
}

export default MyApp;

3. Using the useToast Hook

You can use the useToast hook to display toasts anywhere in your application. Note that if you provide the customVariantClasses property, it will completely override the default styling defined by the variant property. Also, the toast function now accepts an image property that can be either a string (typically a URL) or a React node.

import { useToast } from 'react-custom-toaster';

function MyComponent() {
  // Optionally limit the number of toasts in view
  const toastOptions = { toastLimit: 3 };
  const { toast } = useToast(toastOptions);

  const handleClick = () => {
    toast({
      title: "Success",
      description: "The operation completed successfully.",
      variant: "success", // This variant's default styling is ignored if customVariantClasses is provided.
      customVariantClasses: "bg-green-100 text-green-800", // Overrides variant styling completely.
      image: "https://example.com/success.png",
      onShow: () => console.log("Toast is shown"),
      onClose: () => console.log("Toast is closed"),
      onDisappearNaturally: () => console.log("Toast disappeared naturally"),
      onOpenChange: (open) => console.log("Controlled open state:", open),
    });
  };

  return <button onClick={handleClick}>Show Toast</button>;
}

API

useToast

The useToast hook provides a toast function that accepts an options object with the following properties:

• title: The toast title (optional)
• description: The toast description (optional)
• variant: The toast variant ('default' | 'success' | 'warning' | 'destructive' | 'info'). Note that this styling will be bypassed if customVariantClasses is provided.
• duration: The duration of the toast in milliseconds (default is 5000)
• action: An action element for the toast (optional)
• icon: An icon for the toast (optional)
• image: A property for displaying an image. It accepts either a string (typically the image URL) or a React node (optional)
• customVariantClasses: Custom CSS classes for the toast variant (optional – overrides variant styling if provided)
• onShow: Callback function executed when the toast shows (optional)
• onClose: Callback function executed when the toast is closed (optional)
• onDisappearNaturally: Callback fired when the toast disappears after its duration (optional)
• onOpenChange: Callback for changes in the open state of the toast, useful for controlled mode (optional)

Additionally, useToast accepts an options parameter (UseToastOptions) with:

• toastLimit: (number) The maximum number of visible toasts at a time.

Components

• ToastProvider: Provides context for toasts.
• Toaster: Renders the toasts.
• Toast: Base toast component.
• ToastTitle: Component for the toast title.
• ToastDescription: Component for the toast description.
• ToastClose: Component to close the toast.
• ToastAction: Component for actions in the toast.

Customization

Customize the appearance of the toasts using Tailwind CSS classes or by overriding the default styles. Remember, if you use customVariantClasses, the default styling from the variant property is not applied.

Example

import { useToast } from 'react-custom-toaster';
import { CheckCircle } from 'lucide-react';

function MyComponent() {
  const { toast } = useToast({ toastLimit: 3 });

  const showSuccessToast = () => {
    toast({
      title: "Operation Successful",
      description: "Changes have been saved successfully.",
      variant: "success",
      customVariantClasses: "bg-green-100 text-green-800", // Overrides default variant styling entirely.
      icon: <CheckCircle className="h-5 w-5 text-green-500" />,
      // Example of providing an image using a React node
      image: <img src="https://example.com/success.png" alt="Success" />,
      duration: 3000,
      onShow: () => console.log("Toast display started"),
      onClose: () => console.log("Toast closed"),
      onDisappearNaturally: () => console.log("Toast disappeared after timeout"),
      onOpenChange: (open) => console.log("Toast open state changed:", open),
    });
  };

  return <button onClick={showSuccessToast}>Save Changes</button>;
}

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/YourFeature).
3. Make your changes and commit them (git commit -m 'Add some feature').
4. Push to the branch (git push origin feature/YourFeature).
5. Open a pull request.

Ensure your code follows the project's coding standards and includes relevant tests.

License

This project is licensed under the MIT License.