https://github.com/kenzycodex/react-cloudbox-alerts
A flexible and customizable alert system for React applications
https://github.com/kenzycodex/react-cloudbox-alerts
Last synced: 4 months ago
JSON representation
A flexible and customizable alert system for React applications
- Host: GitHub
- URL: https://github.com/kenzycodex/react-cloudbox-alerts
- Owner: kenzycodex
- License: mit
- Created: 2025-03-12T01:48:39.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-12T02:54:38.000Z (over 1 year ago)
- Last Synced: 2025-03-12T03:31:24.632Z (over 1 year ago)
- Language: JavaScript
- Size: 40 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# React Cloudbox Alerts
A flexible and powerful alert system for React applications.
React Cloudbox Alerts provides a complete solution for displaying notifications, toasts, confirmations, and progress indicators in your React applications. With a focus on flexibility, performance, and developer experience, this library makes it easy to add beautiful alerts with minimal setup.
## Features
- 🚀 **Global Alert System** - Show alerts from anywhere in your application
- ✨ **Multiple Alert Types** - Success, error, warning, info, and custom alerts
- 🎭 **Animations** - Smooth entrance and exit animations
- 🌗 **Dark Mode Support** - Seamless integration with light/dark themes
- 📱 **Responsive Design** - Works on all screen sizes
- 🔧 **Highly Customizable** - Tailor alerts to match your application's design
- 🧩 **Modular Architecture** - Use only what you need
- 📦 **Small Footprint** - Minimal impact on your bundle size
- 🧪 **Well Tested** - Comprehensive test coverage
## Documentation
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Advanced Usage](#advanced-usage)
- [API Reference](#api-reference)
- [Browser Support](#browser-support)
- [Changelog](CHANGELOG.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [License](LICENSE)
For full documentation and examples, visit our [Storybook](https://kenzycodex.github.io/react-cloudbox-alerts).
## Installation
```bash
# npm
npm install react-cloudbox-alerts
# yarn
yarn add react-cloudbox-alerts
# pnpm
pnpm add react-cloudbox-alerts
```
## Quick Start
### 1. Set up the AlertContainer
Add the `AlertContainer` component at the root level of your application:
```jsx
import React from 'react';
import { AlertContainer } from 'react-cloudbox-alerts';
function App() {
return (
{/* Add AlertContainer at the root level */}
{/* Your application content */}
My Application
{/* ... */}
);
}
export default App;
```
### 2. Show alerts using AlertService
Now you can trigger alerts from anywhere in your application:
```jsx
import React from 'react';
import { AlertService } from 'react-cloudbox-alerts';
function Dashboard() {
const handleSave = () => {
// Save data
AlertService.success('Data saved successfully!');
};
const handleError = () => {
AlertService.error('An error occurred during the operation.');
};
return (
Dashboard
Save Data
Trigger Error
);
}
export default Dashboard;
```
## Advanced Usage
### Theme Integration
The library includes a built-in theme provider that integrates with your application's theme:
```jsx
import React from 'react';
import { AlertContainer, ThemeProvider } from 'react-cloudbox-alerts';
function App() {
return (
{/* Your application content */}
);
}
export default App;
```
### Custom Alert Styling
Customize the appearance of alerts to match your application's design:
```jsx
import React from 'react';
import { AlertContainer } from 'react-cloudbox-alerts';
function App() {
return (
{/* Your application content */}
);
}
export default App;
```
### Confirmation Alerts
Show alerts that require user confirmation:
```jsx
import { AlertService } from 'react-cloudbox-alerts';
async function deleteItem() {
try {
await AlertService.confirm('Are you sure you want to delete this item?', {
confirmText: 'Delete',
cancelText: 'Cancel',
variant: 'danger'
});
// User confirmed, proceed with deletion
await deleteItemFromDatabase();
AlertService.success('Item deleted successfully!');
} catch (error) {
// User cancelled or an error occurred
console.log('Operation cancelled');
}
}
```
### Progress Alerts
Show alerts with progress indicators:
```jsx
import { AlertService } from 'react-cloudbox-alerts';
function uploadFile(file) {
// Create a progress alert
const progressAlert = AlertService.progress('Uploading file...', {
variant: 'info',
withIcon: true,
});
// Update progress as the operation proceeds
const uploadTask = createUploadTask(file);
uploadTask.on('progress', (snapshot) => {
const progress = snapshot.bytesTransferred / snapshot.totalBytes;
progressAlert.update(`Uploading: ${Math.round(progress * 100)}%`, progress);
});
uploadTask.on('success', () => {
progressAlert.complete('File uploaded successfully!');
});
uploadTask.on('error', (error) => {
progressAlert.error(`Upload failed: ${error.message}`);
});
}
```
## API Reference
### Components
#### ``
The container component that manages and displays alerts.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | string | `'top-right'` | Position of alerts on the screen. Options: `'top-right'`, `'top-left'`, `'top-center'`, `'bottom-right'`, `'bottom-left'`, `'bottom-center'` |
| `newestOnTop` | boolean | `true` | Whether to show newest alerts on top |
| `limit` | number | `5` | Maximum number of alerts to show at once (0 = unlimited) |
| `spacing` | number | `10` | Space between alerts in pixels |
| `containerWidth` | number | `300` | Container width in pixels |
| `iconSet` | string | `'ri'` | Icon set to use (e.g., 'ri' for Remix Icons, 'fa' for Font Awesome) |
| `darkMode` | boolean | - | Override dark mode from theme context |
| `offset` | number | `20` | Offset from edge of screen in pixels |
| `zIndex` | number | `9999` | Z-index of the container |
#### ``
The individual alert component (usually used internally by `AlertContainer`).
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | string | `'primary'` | Alert style variant: `'primary'`, `'secondary'`, `'success'`, `'danger'`, `'warning'`, `'info'`, `'light'` |
| `withIcon` | boolean | `false` | Whether to display an icon |
| `withBackground` | boolean | `false` | Use colored background instead of colored text |
| `dismissible` | boolean | `false` | Whether the alert can be dismissed |
| `icon` | string | - | Custom icon class (defaults based on variant) |
| `autoHideDuration` | number | `0` | Auto-hide duration in milliseconds (0 = no auto-hide) |
| `animation` | string | `'fade'` | Animation type: `'fade'`, `'slide'`, `'bounce'`, `'zoom'`, `'slide-up'`, `'slide-down'`, `'slide-left'`, `'slide-right'` |
| `position` | string | `'top'` | Alert position for animations: `'top'`, `'bottom'`, `'left'`, `'right'`, `'center'` |
| `className` | string | - | Additional CSS classes |
| `onDismiss` | function | - | Callback function when alert is dismissed |
| `children` | node | - | Alert content |
#### ``
Provider component for theme context.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultDarkMode` | boolean | `false` | Initial dark mode state |
| `children` | node | - | Child components |
### Services
#### `AlertService`
Service for showing alerts programmatically.
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `show` | `(message, options)` | `alertId` | Shows a generic alert |
| `success` | `(message, options)` | `alertId` | Shows a success alert |
| `error` | `(message, options)` | `alertId` | Shows an error alert |
| `warning` | `(message, options)` | `alertId` | Shows a warning alert |
| `info` | `(message, options)` | `alertId` | Shows an info alert |
| `remove` | `(alertId)` | - | Removes an alert by ID |
| `clear` | - | - | Removes all alerts |
| `confirm` | `(message, options)` | `Promise` | Shows a confirmation alert |
| `progress` | `(message, options)` | `{update, complete, error}` | Shows a progress alert |
### Hooks
#### `useTheme`
Hook to access theme context.
```jsx
import { useTheme } from 'react-cloudbox-alerts';
function MyComponent() {
const { darkMode, toggleTheme } = useTheme();
return (
Switch to {darkMode ? 'Light' : 'Dark'} Mode
);
}
```
## Browser Support
React Cloudbox Alerts supports all modern browsers:
- Chrome (and Chromium-based browsers like Edge)
- Firefox
- Safari
- Opera
## Contributing
We welcome contributions from the community! Please check out our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started and our [Code of Conduct](CODE_OF_CONDUCT.md) for our community standards.
## Versioning
This project follows [Semantic Versioning](https://semver.org/). For the versions available, see the [tags on this repository](https://github.com/kenzycodex/react-cloudbox-alerts/tags).
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.