- 🔔 free-alerts
- 🔔 Toast Methods
- 📢 Alert Method
- ❓ Confirm Method
Open Demo View on NPM GitHub Repository
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.
- 🔔 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
Before using the library, make sure you have:
- 🌐 Modern browser
- 📦 Node.js (for package installation)
- 📦 npm
npm install free-alertsimport FreeAlerts from 'free-alerts';
import 'free-alerts/style';
FreeAlerts.success('Operation completed successfully');<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/free-alerts@1.0.0/dist/free-alerts.css" /><script src="https://cdn.jsdelivr.net/npm/free-alerts@1.0.0/dist/free-alerts.umd.js"></script><button id="btn">Show Toast</button>
<script>
document.getElementById('btn').addEventListener('click', () => {
FreeAlerts.success('Hello World!');
});
</script>| 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 |
The following methods display temporary notifications:
FreeAlerts.success();
FreeAlerts.error();
FreeAlerts.warning();
FreeAlerts.info();message: string
options?: {
duration?: number
}FreeAlerts.success('User created successfully');FreeAlerts.error('Unexpected error occurred');FreeAlerts.warning('Please complete all fields');FreeAlerts.info('New version available');FreeAlerts.success('Saved correctly', {
duration: 5000,
});Displays an informational modal dialog.
{
title?: string;
message?: string;
}FreeAlerts.alert({
title: 'Attention',
message: 'This action cannot be undone.',
});Displays a confirmation dialog and returns a Promise.
{
title?: string;
message?: string;
}Promise<boolean>;const confirmed = await FreeAlerts.confirm({
title: 'Delete User',
message: 'Are you sure you want to continue?',
});
if (confirmed) {
console.log('Confirmed');
}document.getElementById('form').addEventListener('submit', () => {
FreeAlerts.success('Form submitted successfully');
});try {
await saveData();
} catch {
FreeAlerts.error('Failed to save data');
}const confirmed = await FreeAlerts.confirm({
title: 'Delete Record',
message: 'This action cannot be undone.',
});
if (confirmed) {
deleteRecord();
}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;There are two ways to use FreeAlerts in Angular depending on TypeScript configuration.
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');
}
}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';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');
}
}- No
@ts-ignoreneeded when using.d.tsfiles - Keeps Angular clean and fully typed
<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>The library includes unit tests using Vitest.
npm run testimport { 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();
});
});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
- 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
Contributions are welcome.
git clone git@github.com:alobuuls/free-alerts.gitnpm installnpm run devnpm run testnpm run buildIf you find bugs, have ideas for improvements, or want to contribute new features, feel free to open an issue or submit a pull request.
This project is intended for educational and portfolio purposes.
Created by Alondra Francisco.