@abisheks238/react-toaster
Version:
An advanced, customizable toast notification system for React with smart queue, swipe support, and theming
347 lines (275 loc) • 9.8 kB
Markdown
# @abisheks238/react-toaster
[](https://badge.fury.io/js/@abisheks238%2Freact-toaster)
[](https://www.npmjs.com/package/@abisheks238/react-toaster)
[](https://github.com/ABISHEK-K-DEV/react-toaster/blob/main/LICENSE)
[](https://github.com/ABISHEK-K-DEV/react-toaster/stargazers)
[](https://bundlephobia.com/package/@abisheks238/react-toaster)
[](https://www.typescriptlang.org/)
An advanced, customizable toast notification system for React applications with smart queue management, swipe gestures, and theming support.
## 🚀 Features
- 🌈 **Multiple toast types**: success, error, info, warning, loading, custom
- 🎨 **Theming support**: Light, dark, and auto themes
- 📱 **Swipe gestures**: Dismiss toasts with swipe actions
- 🔄 **Smart queue management**: Priority-based toast handling
- 📍 **Flexible positioning**: 7 different positions available
- ⏱️ **Auto-dismiss**: Customizable duration with pause on hover
- 🎯 **Action buttons**: Add custom actions to toasts
- 🔊 **Sound & Vibration**: Optional audio and haptic feedback
- 🧩 **Fully typed**: Complete TypeScript support
- 🎭 **Animations**: Smooth enter/exit animations
- 📦 **Lightweight**: Minimal bundle size
## 📦 Installation
```bash
# npm
npm install @abisheks238/react-toaster
# yarn
yarn add @abisheks238/react-toaster
# pnpm
pnpm add @abisheks238/react-toaster
```
**✅ Just Published!** Latest version available on npm: `v1.0.2`
## 🔗 Links
- [📦 NPM Package](https://www.npmjs.com/package/@abisheks238/react-toaster)
- [📚 GitHub Repository](https://github.com/ABISHEK-K-DEV/react-toaster)
- [🐛 Report Issues](https://github.com/ABISHEK-K-DEV/react-toaster/issues)
- [💡 Feature Requests](https://github.com/ABISHEK-K-DEV/react-toaster/issues/new)
## 🚀 Quick Start
### 1. Wrap your application with ToasterProvider
```tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { ToasterProvider } from '@abisheks238/react-toaster';
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
<React.StrictMode>
<ToasterProvider theme="auto" position="top-right">
<App />
</ToasterProvider>
</React.StrictMode>
);
```
### 2. Use the toaster in your components
```tsx
import React from 'react';
import { useToaster } from '@abisheks238/react-toaster';
function MyComponent() {
const { success, error, info, warning, loading } = useToaster();
return (
<div>
<button onClick={() => success('Operation successful!')}>
Show Success Toast
</button>
<button onClick={() => error('Something went wrong.')}>
Show Error Toast
</button>
<button onClick={() => info('Here is some information.')}>
Show Info Toast
</button>
<button onClick={() => warning('Proceed with caution!')}>
Show Warning Toast
</button>
<button onClick={() => loading('Processing...')}>
Show Loading Toast
</button>
{/* Advanced usage with actions */}
<button
onClick={() =>
error('Failed to save changes', {
position: 'bottom-center',
duration: 10000,
actions: [
{
label: 'Retry',
onClick: (id) => console.log('Retry clicked', id),
style: 'primary'
},
{
label: 'Cancel',
onClick: (id) => console.log('Cancel clicked', id),
style: 'secondary'
}
],
onRetry: () => console.log('Retry action triggered'),
sound: true,
vibrate: true
})
}
>
Advanced Toast
</button>
</div>
);
}
```
## 📖 API Reference
### ToasterProvider Props
```tsx
interface ToasterProviderProps {
children: ReactNode;
theme?: 'light' | 'dark' | 'auto'; // Default: 'auto'
queue?: {
maxToasts?: number; // Default: 5
strategy?: 'fifo' | 'lifo' | 'priority'; // Default: 'fifo'
grouping?: boolean; // Default: false
maxPerGroup?: number; // Default: 3
};
defaultConfig?: Partial<ToastConfig>;
containerClassName?: string;
newestOnTop?: boolean; // Default: true
richColors?: boolean; // Default: true
closeButton?: boolean; // Default: true
}
```
### useToaster Hook
```tsx
const {
success,
error,
info,
warning,
loading,
custom,
update,
dismiss,
dismissAll,
dismissGroup,
pause,
resume,
retry,
undo,
setTheme,
setQueue
} = useToaster();
```
### Toast Configuration Options
```tsx
interface ToastConfig {
position?: 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center' | 'center';
duration?: number; // milliseconds (default: 5000, use Infinity for persistent)
priority?: 'low' | 'normal' | 'high' | 'urgent';
dismissible?: boolean; // Default: true
pauseOnHover?: boolean; // Default: true
pauseOnFocusLoss?: boolean; // Default: true
swipe?: {
enabled: boolean; // Default: true
threshold: number; // Default: 100
velocity: number; // Default: 0.3
};
icon?: ReactNode | boolean; // Default: true
sound?: boolean; // Default: false
vibrate?: boolean; // Default: false
actions?: ToastAction[];
onClose?: () => void;
onUndo?: () => void;
onRetry?: () => void;
className?: string;
style?: CSSProperties;
groupId?: string;
stackable?: boolean;
}
```
## 🎨 Theming
The toaster automatically adapts to your system's color scheme when using `theme="auto"`. You can also force light or dark themes:
```tsx
<ToasterProvider theme="dark">
<App />
</ToasterProvider>
// Or change theme dynamically
const { setTheme } = useToaster();
setTheme('light');
```
## 🎭 Advanced Features
### Queue Management
```tsx
const { setQueue } = useToaster();
// Configure queue behavior
setQueue({
maxToasts: 3,
strategy: 'priority', // Show high priority toasts first
grouping: true, // Group similar toasts
maxPerGroup: 2
});
```
### Custom Actions
```tsx
success('File uploaded successfully!', {
actions: [
{
label: 'View File',
onClick: (id) => openFile(),
style: 'primary'
},
{
label: 'Share',
onClick: (id) => shareFile(),
style: 'secondary'
}
],
onUndo: () => deleteFile() // Undo action
});
```
### Swipe Gestures
```tsx
info('Swipe me away!', {
swipe: {
enabled: true,
threshold: 150, // Pixels to trigger dismiss
velocity: 0.5 // Minimum swipe velocity
}
});
```
## 🔧 Troubleshooting
### Package not showing in GitHub?
If your npm package isn't appearing in the GitHub "Packages" section:
1. **Wait for sync**: GitHub can take up to 24 hours to detect new packages
2. **Verify repository URL**: Check that your package.json has the correct repository URL
3. **Manual linking**: Go to your repository Settings → Packages → Connect repository
### Verification Commands
```bash
# Check package info
npm info @abisheks238/react-toaster
# Verify installation
npm install @abisheks238/react-toaster --dry-run
# Check repository link
npm view @abisheks238/react-toaster repository
```
### Common Issues
- **Import errors**: Make sure you're importing from the correct path
- **TypeScript issues**: Ensure you have React types installed
- **Styling not working**: Import the CSS or configure Tailwind properly
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://github.com/ABISHEK-K-DEV/react-toaster/blob/main/CONTRIBUTING.md) for details.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 🆕 What's New
### v1.0.2 (Latest)
- ✅ Published to npm registry
- 🔗 Linked to GitHub repository
- 📚 Enhanced documentation
- 🐛 Fixed repository metadata
### v1.0.1
- 🎨 Advanced theming support
- 📱 Swipe gesture implementation
- 🔄 Smart queue management
- 🎯 Action buttons support
## 📊 Stats
- 📦 **Bundle Size**: < 50KB minified + gzipped
- 🎯 **TypeScript**: 100% coverage
- 🧪 **React Support**: 16.8+ (Hooks required)
- 🌐 **Browser Support**: Modern browsers (ES2015+)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/ABISHEK-K-DEV/react-toaster/blob/main/LICENSE) file for details.
## 🙏 Acknowledgments
- Built with ❤️ by [Abishek](https://github.com/ABISHEK-K-DEV)
- Inspired by modern toast notification patterns
- Powered by React and TypeScript
---
**Made with ❤️ for the React community**
[](https://www.npmjs.com/package/@abisheks238/react-toaster)
### 📈 GitHub Package Detection
> **Note**: If you don't see this package in the GitHub "Packages" section yet, don't worry! GitHub typically takes 12-24 hours to sync with npm. The package is live and ready to use.
**Quick verification**: Visit [npm package page](https://www.npmjs.com/package/@abisheks238/react-toaster) to confirm it's published successfully.