react-cloudbox-alerts v0.2.5

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
• Quick Start
• Advanced Usage
• API Reference
• Browser Support
• Changelog
• Contributing Guidelines
• Code of Conduct
• License

For full documentation and examples, visit our Storybook.

Installation

# 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:

import React from 'react';
import { AlertContainer } from 'react-cloudbox-alerts';

function App() {
  return (
    <div className="app">
      {/* Add AlertContainer at the root level */}
      <AlertContainer position="top-right" />
      
      {/* Your application content */}
      <main>
        <h1>My Application</h1>
        {/* ... */}
      </main>
    </div>
  );
}

export default App;

2. Show alerts using AlertService

Now you can trigger alerts from anywhere in your application:

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 (
    <div>
      <h2>Dashboard</h2>
      <button onClick={handleSave}>Save Data</button>
      <button onClick={handleError}>Trigger Error</button>
    </div>
  );
}

export default Dashboard;

Advanced Usage

Theme Integration

The library includes a built-in theme provider that integrates with your application's theme:

import React from 'react';
import { AlertContainer, ThemeProvider } from 'react-cloudbox-alerts';

function App() {
  return (
    <ThemeProvider>
      <div className="app">
        <AlertContainer />
        {/* Your application content */}
      </div>
    </ThemeProvider>
  );
}

export default App;

Custom Alert Styling

Customize the appearance of alerts to match your application's design:

import React from 'react';
import { AlertContainer } from 'react-cloudbox-alerts';

function App() {
  return (
    <div className="app">
      <AlertContainer 
        position="bottom-center"
        containerWidth={400}
        spacing={15}
        iconSet="fa" // Use Font Awesome icons
      />
      {/* Your application content */}
    </div>
  );
}

export default App;

Confirmation Alerts

Show alerts that require user confirmation:

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:

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

<AlertContainer>

The container component that manages and displays alerts.

<Alert>

The individual alert component (usually used internally by AlertContainer).

<ThemeProvider>

Provider component for theme context.

Services

AlertService

Service for showing alerts programmatically.

Hooks

useTheme

Hook to access theme context.

import { useTheme } from 'react-cloudbox-alerts';

function MyComponent() {
  const { darkMode, toggleTheme } = useTheme();
  
  return (
    <button onClick={toggleTheme}>
      Switch to {darkMode ? 'Light' : 'Dark'} Mode
    </button>
  );
}

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 for details on how to get started and our Code of Conduct for our community standards.

Versioning

This project follows Semantic Versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.