hypertoast

v1.0.2

Published

a month ago

A beautiful, highly customizable React toast notification library with smooth animations, dark/light themes, and TailwindCSS styling

🍞 HyperToast

A beautiful, highly customizable React toast notification library with smooth animations, dark/light themes, and TailwindCSS styling.

🌐 Documentation & Live Preview • 📦 NPM

Features

10 Animation Styles — fade, slide, zoom, bounce, elastic, flip, blur, roll, swing, pop
Dark & Light Themes — Automatic system theme detection
6 Positions — top/bottom + left/center/right
5 Toast Types — success, error, info, warning, loading
Shimmer Effect — Beautiful loading animation
Action Buttons — Customizable call-to-action buttons
Lightweight — ~11KB minified, tree-shakeable
TypeScript — Full type support out of the box

Installation

npm install hypertoast

yarn add hypertoast

pnpm add hypertoast

Prerequisites

HyperToast requires TailwindCSS v3+ in your project. The toasts are styled using Tailwind utility classes.

If you don't have TailwindCSS installed, follow the official guide.

Setup

Step 1: Configure TailwindCSS

Add HyperToast to your tailwind.config.js content paths and add the shimmer animation:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/hypertoast/**/*.{js,mjs}', // 👈 Add this line
  ],
  theme: {
    extend: {
      animation: {
        shimmer: 'shimmer 2s linear infinite',
      },
      keyframes: {
        shimmer: {
          '0%': { backgroundPosition: '200% center' },
          '100%': { backgroundPosition: '-200% center' },
        },
      },
    },
  },
  plugins: [],
};

Step 2: Add the ToastProvider

Wrap your app with ToastProvider:

// App.tsx or _app.tsx or layout.tsx
import { ToastProvider } from 'hypertoast';

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

export default App;

For Next.js App Router (v13+)

Create a client wrapper component:

// components/Providers.tsx
"use client";

import { ToastProvider } from 'hypertoast';

export function Providers({ children }: { children: React.ReactNode }) {
  return <ToastProvider>{children}</ToastProvider>;
}

Then use it in your layout:

// app/layout.tsx
import { Providers } from '@/components/Providers';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Basic Usage

import { useToast } from 'hypertoast';

function MyComponent() {
  const { success, error, info, warning, loading } = useToast();

  return (
    <div>
      <button onClick={() => success('File saved successfully!')}>
        Success
      </button>
      <button onClick={() => error('Failed to save file')}>
        Error
      </button>
      <button onClick={() => info('New update available')}>
        Info
      </button>
      <button onClick={() => warning('Storage almost full')}>
        Warning
      </button>
      <button onClick={() => loading('Uploading...', undefined, true)}>
        Loading
      </button>
    </div>
  );
}

Advanced Usage

Custom Toast with Options

const { toast } = useToast();

toast({
  message: 'File uploaded successfully',
  type: 'success',
  duration: 5000, // 5 seconds (default: 4000)
  shimmer: false,
});

Toast with Action Button

const { toast } = useToast();

toast({
  message: 'Message sent',
  type: 'success',
  action: {
    label: 'Undo',
    onClick: () => {
      console.log('Undo clicked!');
    },
    variant: 'green', // 'default' | 'green' | 'red' | 'yellow' | 'orange'
  },
});

Loading Toast with Shimmer Effect

const { loading } = useToast();

// The third parameter enables the shimmer animation
loading('Processing your request...', undefined, true);

Customization

Change Position

const { setPosition } = useToast();

// Options: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
setPosition('top-right');

Change Animation

const { setAnimation } = useToast();

// Options: 'fade' | 'slide' | 'zoom' | 'bounce' | 'elastic' | 'flip' | 'blur' | 'roll' | 'swing' | 'pop'
setAnimation('bounce');

Change Border Radius

const { setRadius } = useToast();

// Options: 'none' | 'small' | 'medium' | 'large' | 'full'
setRadius('full');

Change Theme

const { setTheme } = useToast();

// Options: 'light' | 'dark' | 'system'
setTheme('dark');

API Reference

ToastProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | — | Your app content | | initialTheme | 'light' \| 'dark' \| 'system' | 'system' | Initial theme setting |

useToast() Return Values

| Method | Parameters | Description | |--------|------------|-------------| | success | (message, action?) | Show success toast | | error | (message, action?) | Show error toast | | info | (message, action?) | Show info toast | | warning | (message, action?) | Show warning toast | | loading | (message, action?, shimmer?) | Show loading toast | | toast | ({ message, type, duration, action, shimmer }) | Show custom toast | | dismiss | (id) | Dismiss a toast by ID | | setPosition | (position) | Change toast position | | setAnimation | (animation) | Change animation style | | setRadius | (radius) | Change border radius | | setTheme | (theme) | Change theme |

ToastAction Object

| Property | Type | Required | Description | |----------|------|----------|-------------| | label | string | ✅ | Button text | | onClick | () => void | ✅ | Click handler | | variant | 'default' \| 'green' \| 'red' \| 'yellow' \| 'orange' | ❌ | Button color |

TypeScript

HyperToast is written in TypeScript and exports all types:

import type {
  Toast,
  ToastAction,
  ToastType,
  ToastPosition,
  ToastAnimation,
  ToastRadius,
  ToastTheme,
} from 'hypertoast';

Framework Compatibility

| Framework | Status | Notes | |-----------|--------|-------| | Vite + React | ✅ | Works out of the box | | Next.js (Pages Router) | ✅ | Works out of the box | | Next.js (App Router) | ✅ | Use "use client" wrapper | | Create React App | ✅ | Works out of the box | | Remix | ✅ | Works out of the box | | Gatsby | ✅ | Works out of the box |

License

MIT © DAZ

Issues & Feature Requests

Found a bug or have a feature request? Email us at [email protected].