🔔 free-alerts

📑 Table of Contents

• 🔔 free-alerts
  • 📑 Table of Contents
  • 🌐 Links
    • 🚀 Demo
    • 📦 NPM Package
    • 💻 Repository
  • 📖 Description
  • ✨ Features
  • ⚙️ System Requirements
  • 🚀 Installation
    • Install from NPM
  • ▶️ Quick Start
  • 🌍 CDN Usage
    • CSS
    • JavaScript
    • Example
  • 📚 API Reference
• 🔔 Toast Methods
  • 🧩 Parameters
  • 🟢 Success
  • 🔴 Error
  • 🟡 Warning
  • 🔵 Info
  • ⏱️ Custom Duration
• 📢 Alert Method
  • 🧩 Parameters
  • Example
• ❓ Confirm Method
  • Parameters
  • Return Type
  • Example
  • 💡 Usage Examples
    • Form Submission
    • Error Handling
    • Delete Confirmation
  • ⚛️ React Example
  • 🅰️ Angular Example
  • 🧩 Option 1 — Using @ts-ignore
  • 🧩 Option 2 — Recommended (Type Declarations)
    • 📝 Type Setup
    • ⚡ Angular Usage
    • 💡 Notes
  • 💚 Vue Example
  • 🧪 Testing
    • Run Tests
    • Example Test
  • 📁 Project Structure
  • 🔥 Best Practices
  • 🤝 Contributing
    • Clone Repository
    • Install Dependencies
    • Start Development Mode
    • Run Tests
    • Build Package
  • 📄 License

🌐 Links

🚀 Demo

📦 NPM Package

💻 Repository

📖 Description

[!NOTE] free-alerts is a lightweight JavaScript library designed to display modern notifications, alerts, and confirmation dialogs with a simple and intuitive API.

The library was created to provide a clean user experience without external dependencies, making it easy to integrate into any JavaScript application or framework.

✨ Features

• 🔔 Toast notifications
• ✅ Success notifications
• ❌ Error notifications
• ⚠️ Warning notifications
• ℹ️ Info notifications
• 📢 Alert dialogs
• ❓ Confirmation dialogs
• 🚀 Zero dependencies
• 🎨 Customizable through CSS
• 📦 Framework agnostic
• ⚡ Lightweight and fast
• 🧪 Tested with Vitest
• 🌍 Browser compatible
• 🔧 Easy integration

⚙️ System Requirements

Before using the library, make sure you have:

• 🌐 Modern browser
• 📦 Node.js (for package installation)
• 📦 npm

🚀 Installation

Install from NPM

npm install free-alerts

▶️ Quick Start

import FreeAlerts from 'free-alerts';
import 'free-alerts/style';

FreeAlerts.success('Operation completed successfully');

🌍 CDN Usage

CSS

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/free-alerts.css" />

JavaScript

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/free-alerts.umd.js"></script>

Example

<button id="btn">Show Toast</button>

<script>
  document.getElementById('btn').addEventListener('click', () => {
    FreeAlerts.success('Hello World!');
  });
</script>

📚 API Reference

| Method | Description | | --------------------------- | ------------------------------- | | success(message, options) | 🟢 Shows a success notification | | error(message, options) | 🔴 Shows an error notification | | warning(message, options) | 🟡 Shows a warning notification | | info(message, options) | 🔵 Shows an info notification | | alert(options) | 🪟 Opens an informational modal | | confirm(options) | ❓ Opens a confirmation modal |

🔔 Toast Methods

The following methods display temporary notifications:

FreeAlerts.success();
FreeAlerts.error();
FreeAlerts.warning();
FreeAlerts.info();

🧩 Parameters

message: string

options?: {
  duration?: number
}

🟢 Success

FreeAlerts.success('User created successfully');

🔴 Error

FreeAlerts.error('Unexpected error occurred');

🟡 Warning

FreeAlerts.warning('Please complete all fields');

🔵 Info

FreeAlerts.info('New version available');

⏱️ Custom Duration

FreeAlerts.success('Saved correctly', {
  duration: 5000,
});

📢 Alert Method

Displays an informational modal dialog.

🧩 Parameters

{
  title?: string;
  message?: string;
}

Example

FreeAlerts.alert({
  title: 'Attention',
  message: 'This action cannot be undone.',
});

❓ Confirm Method

Displays a confirmation dialog and returns a Promise.

Parameters

{
  title?: string;
  message?: string;
}

Return Type

Promise<boolean>;

Example

const confirmed = await FreeAlerts.confirm({
  title: 'Delete User',
  message: 'Are you sure you want to continue?',
});

if (confirmed) {
  console.log('Confirmed');
}

💡 Usage Examples

Form Submission

document.getElementById('form').addEventListener('submit', () => {
  FreeAlerts.success('Form submitted successfully');
});

Error Handling

try {
  await saveData();
} catch {
  FreeAlerts.error('Failed to save data');
}

Delete Confirmation

const confirmed = await FreeAlerts.confirm({
  title: 'Delete Record',
  message: 'This action cannot be undone.',
});

if (confirmed) {
  deleteRecord();
}

⚛️ React Example

import FreeAlerts from 'free-alerts';
import 'free-alerts/style';

function App() {
  const handleClick = () => {
    FreeAlerts.success('Saved from React');
  };

  return <button onClick={handleClick}>Save</button>;
}

export default App;

🅰️ Angular Example

There are two ways to use FreeAlerts in Angular depending on TypeScript configuration.

🧩 Option 1 — Using @ts-ignore

import { Component } from '@angular/core';

// @ts-ignore
import FreeAlerts from 'free-alerts';

// @ts-ignore
import 'free-alerts/style';

@Component({
  selector: 'app-root',
  template: '<button (click)="showAlert()">Show alert</button>',
})
export class AppComponent {
  showAlert(): void {
    FreeAlerts.success('test');
  }
}

🧩 Option 2 — Recommended (Type Declarations)

📝 Type Setup

Create the TypeScript declaration file:

src/types/free-alerts.d.ts

// This is for the FreeAlerts  ↓
declare module 'free-alerts' {
  const FreeAlerts: {
    success(message: string, options?: Record<string, any>): void;
    error(message: string, options?: Record<string, any>): void;
    warning(message: string, options?: Record<string, any>): void;
    info(message: string, options?: Record<string, any>): void;
    alert(options: { title?: string; message?: string }): void;
    confirm(options: { title?: string; message?: string }): Promise<boolean>;
  };
  export default FreeAlerts;
}

// This is for the styles  ↓
declare module 'free-alerts/style';

⚡ Angular Usage

import { Component } from '@angular/core';

//  Imports here ↓
import FreeAlerts from 'free-alerts';
import 'free-alerts/style';

@Component({
  selector: 'app-root',
  template: '<button (click)="showAlert()">Show alert</button>',
})
export class AppComponent {
  showAlert(): void {
    FreeAlerts.success('test');
  }
}

💡 Notes

• No @ts-ignore needed when using .d.ts files
• Keeps Angular clean and fully typed

💚 Vue Example

<template>
  <button @click="notify">Notify</button>
</template>

<script setup>
import FreeAlerts from 'free-alerts';
import 'free-alerts/style';

function notify() {
  FreeAlerts.success('Saved from Vue');
}
</script>

🧪 Testing

The library includes unit tests using Vitest.

Run Tests

npm run test

Example Test

import { describe, it, expect } from 'vitest';
import FreeAlerts from '../src/index.js';

describe('FreeAlerts.alert', () => {
  it('should create modal', () => {
    FreeAlerts.alert({
      title: 'Error',
      message: 'Something happened',
    });

    const modal = document.querySelector('.free-alerts-modal');

    expect(modal).not.toBeNull();
  });
});

📁 Project Structure

free-alerts/
├── demo/
│   ├── dev/
│   │   ├── app.js
│   │   ├── index.html
│   │   └── styles.css
│   └── prod/
│       ├── app.js
│       ├── index.html
│       └── styles.css
│
├── dist/
│   ├── free-alerts.css
│   ├── free-alerts.mjs
│   └── free-alerts.umd.js
│
├── src/
│   ├── assets/
│   │   └── preview.png
│   │
│   ├── core/
│   │   ├── alert.js
│   │   ├── confirm.js
│   │   ├── createElement.js
│   │   └── toast.js
│   │
│   ├── styles/
│   │   └── free-alerts.css
│   │
│   ├── utils/
│   │   ├── constants.js
│   │   └── icons.js
│   │
│   └── index.js
│
├── tests/
│   ├── alert.test.js
│   ├── confirm.test.js
│   └── setup.js
│
├── package.json
├── package-lock.json
├── vite.config.js
├── vitest.config.js
├── LICENSE
└── README.md

🔥 Best Practices

• Use success notifications for successful operations
• Use error notifications for failures
• Use confirm dialogs before destructive actions
• Keep messages concise and meaningful
• Avoid excessive notifications
• Maintain consistent user feedback
• Provide clear action outcomes

🤝 Contributing

Contributions are welcome.

Clone Repository

git clone [email protected]:alobuuls/free-alerts.git

Install Dependencies

npm install

Start Development Mode

npm run dev

Run Tests

npm run test

Build Package

npm run build

If you find bugs, have ideas for improvements, or want to contribute new features, feel free to open an issue or submit a pull request.

📄 License

This project is intended for educational purposes and is part of a personal portfolio.