🍞 react-inspire-toast

A lightweight, customizable React toast notification library with built-in support for inspiring quotes. Show beautiful toast notifications with different types, automatic dismissal, and optional quote fetching from an external API.

✨ Features

• Four Toast Types: info, success, warning, error
• Auto-dismiss: Toasts automatically disappear after a configurable duration
• Quote Integration: Built-in function to fetch and display random inspiring quotes
• TypeScript Support: Fully typed with TypeScript
• Context API: Uses React Context for clean, dependency-injection style API
• Lightweight: Minimal bundle size (~4.7 kB gzipped)
• Message Truncation: Optional text truncation for long messages
• Zero Dependencies: Only requires React (18+)

📦 Installation

npm install react-inspire-toast

Or with yarn:

yarn add react-inspire-toast

🚀 Quick Start

1. Wrap your app with ToastProvider

import { ToastProvider } from "react-inspire-toast";

function App() {
  return (
    <ToastProvider>
      <YourComponent />
    </ToastProvider>
  );
}

export default App;

2. Use the useToast hook to show toasts

import { useToast } from "react-inspire-toast";

function MyComponent() {
  const { addToast } = useToast();

  return (
    <button onClick={() => addToast("Hello!", "success")}>
      Show Toast
    </button>
  );
}

📚 API Reference

ToastProvider

Wraps your app and provides the toast context.

<ToastProvider>
  <App />
</ToastProvider>

Props:

• children: React node to wrap

useToast()

Hook to access toast functionality. Must be used inside a ToastProvider.

const { addToast } = useToast();

Returns:

• addToast(message, type?, duration?, options?): Function to show a toast

addToast(message, type, duration, options)

Shows a toast notification.

Parameters:

| Parameter | Type | Default | Description | | ---------- | --------------------------------------------- | -------- | ----------------------------- | | message | string | required | The toast message | | type | 'info' \| 'success' \| 'warning' \| 'error' | 'info' | Toast style/color | | duration | number | 4000 | Time before auto-dismiss (ms) | | options | ToastOptions | - | Additional options |

ToastOptions:

interface ToastOptions {
  truncate?: number; // Max message length before adding "..."
}

showQuoteToast(addToast, duration, type)

Fetches a random quote and displays it as a toast.

Parameters:

| Parameter | Type | Default | Description | | ---------- | -------- | -------- | ----------------------------------- | | addToast | function | required | The addToast function from useToast | | duration | number | 4000 | Toast display time (ms) | | type | string | 'info' | Toast type |

📖 Usage Examples

Basic Toast Notifications

import { useToast } from "react-inspire-toast";

function MyComponent() {
  const { addToast } = useToast();

  return (
    <div>
      <button onClick={() => addToast("Info message", "info")}>
        Info
      </button>

      <button onClick={() => addToast("Success!", "success")}>
        Success
      </button>

      <button onClick={() => addToast("Error occurred", "error")}>
        Error
      </button>

      <button onClick={() => addToast("Warning!", "warning")}>
        Warning
      </button>
    </div>
  );
}

With Custom Duration

const { addToast } = useToast();

// Show toast for 6 seconds
addToast("Long message", "info", 6000);

With Message Truncation

const { addToast } = useToast();

const longText = "This is a very long message that might be too long for the toast";

// Truncate to 30 characters
addToast(longText, "info", 4000, { truncate: 30 });
// Displays: "This is a very long message..."

Show Random Quote

import { useToast, showQuoteToast } from "react-inspire-toast";

function QuoteButton() {
  const { addToast } = useToast();

  const handleClick = () => {
    showQuoteToast(addToast, 5000, "info");
  };

  return <button onClick={handleClick}>Show Random Quote 💡</button>;
}

Complete Example

import { ToastProvider, useToast, showQuoteToast } from "react-inspire-toast";

function TestButtons() {
  const { addToast } = useToast();

  return (
    <div style={{ padding: "50px" }}>
      <h1>Toast Test 🍞</h1>

      <div style={{ display: "flex", gap: "10px", flexDirection: "column", maxWidth: "300px" }}>
        <button onClick={() => addToast("Info message", "info")}>
          Show Info Toast
        </button>

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

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

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

        <QuoteButton />
      </div>
    </div>
  );
}

function QuoteButton() {
  const { addToast } = useToast();

  const handleClick = () => {
    showQuoteToast(addToast, 5000, "info");
  };

  return <button onClick={handleClick}>Show Random Quote 💡</button>;
}

function App() {
  return (
    <ToastProvider>
      <TestButtons />
    </ToastProvider>
  );
}

export default App;

🎨 Styling

Toasts are styled with the toast.css file included in the package. The library uses the following CSS classes:

• .toast-container: Main container for all toasts
• .toast: Base toast element
• .toast-info: Info styled toast
• .toast-success: Success styled toast (green)
• .toast-warning: Warning styled toast (yellow)
• .toast-error: Error styled toast (red)

You can customize the appearance by overriding these classes in your CSS:

.toast {
  background-color: #333;
  color: white;
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
}

.toast-success {
  background-color: #4caf50;
}

.toast-error {
  background-color: #f44336;
}

.toast-warning {
  background-color: #ff9800;
}

.toast-info {
  background-color: #2196f3;
}

🔧 TypeScript Support

Full TypeScript support out of the box:

import { useToast, type ToastType, type Toast, type ToastOptions } from "react-inspire-toast";

// Use types in your code
const toastType: ToastType = "success";

const options: ToastOptions = {
  truncate: 50,
};

⚠️ Error Handling

If showQuoteToast fails to fetch a quote (network error, API down, etc.), it will automatically show an error toast:

showQuoteToast(addToast, 5000, "info");
// If fetch fails → Shows: "Failed to fetch quote" (error type)

❌ Common Errors

"useToast must be used within ToastProvider"

Make sure your component is wrapped with ToastProvider:

// ❌ Wrong
function App() {
  const { addToast } = useToast(); // Error!
  return <div>...</div>;
}

// ✅ Correct
function App() {
  return (
    <ToastProvider>
      <MyComponent />
    </ToastProvider>
  );
}

function MyComponent() {
  const { addToast } = useToast(); // Works!
  return <div>...</div>;
}

📄 License

MIT

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📮 Support

For issues, feature requests, or questions, visit the GitHub repository.

Made with ❤️ by Mohid Anwar