# π NotifyX v4
### The professional-grade notification library built for the AI era.
**Visually stunning for designers, robust enough for complex architectures, and optimized for real-time AI streaming.**
[](https://www.npmjs.com/package/notifyx)
[](https://www.npmjs.com/package/notifyx)
[](https://bundlephobia.com/package/notifyx)
[](https://www.typescriptlang.org/)
[](LICENSE)
[Demo](https://github.com/awalhadi/notifyx) β’ [Installation](#-installation) β’ [AI Integration](#-ai--mcp-integration) β’ [Stack UI](#-stack-based-ui--priority-queue) β’ [Themes](#-zero-dependency-theme-system)
---
## β¨ Why NotifyX?
NotifyX v4 is engineered from the ground up to solve the challenges of modern web applications. Whether you are building an LLM-powered agent workflow, a Next.js SaaS, or an interactive dashboard, NotifyX delivers a pristine user experience.
### Competitive Differentiation
| Feature | NotifyX v4 | react-hot-toast | sonner | react-toastify |
| :--- | :---: | :---: | :---: | :---: |
| **Stack-Based UI** | β
Elegant 3D | β | β
| β |
| **AI/Streaming API** | β
Native | β | β | β |
| **MCP-Ready** | β
| β | β | β |
| **Web Animations API** | β
GPU Accelerated | β | limited | limited |
| **Theme System** | β
6 robust themes | β | partial | partial |
| **Vanilla JS Support**| β
| β | β | partial |
| **Priority Queue** | β
| β | β | β |
| **Zero Dependencies** | β
| β
| β
| β |
| **Bundle < 7KB** | β
| β
| β
| β |
---
## π¦ Installation
```bash
# npm
npm install notifyx
# pnpm
pnpm add notifyx
# bun
bun add notifyx
```
### Setup
```javascript
import NotifyX from 'notifyx';
import 'notifyx/style.css'; // Required for UI styling
NotifyX.success('Ready for the AI era! π');
```
---
## π Stack-Based UI & Priority Queue
NotifyX v4 departs from legacy list-based rendering, introducing a **Stack-Based Architecture**.
Notifications gracefully stack with dynamic `transform: scale()` and `translateY()` 3D layering, saving vertical screen real estate while feeling incredibly premium.
Under the hood, the **Priority Queue Manager** handles influxes of notifications perfectly. If an application throws 20 events at once, NotifyX will instantly display the allowed maximum (`maxToasts`), gracefully holding the rest in memory and seamlessly rendering them as active toasts are dismissed.
---
## π€ AI & MCP Integration
NotifyX provides first-class support for AI metadata, rendering Model Context Protocol (MCP) tool calls, token counts, and latency flawlessly.
```javascript
NotifyX.ai("Processing context...", {
ai: {
model: "claude-3-5-sonnet",
toolName: "read_file",
latencyMs: 1240,
tokens: 450
}
});
```
It renders elegantly with a custom `β¦` icon, specialized color palettes, and a structured metadata bar showcasing agent workflow steps.
---
## π Streaming API
LLMs stream responses token-by-token. NotifyX's `StreamingBridge` ensures smooth, jank-free progressive text rendering.
```javascript
const stream = NotifyX.stream("Thinking...", {
ai: { model: "gpt-4o", streaming: true },
position: "bottom-right"
});
// Stream chunks as they arrive
stream.update("I have found ");
stream.update("the specific bug ");
stream.update("in your code.");
// Finalize
stream.success("Analysis complete!", {
ai: { streaming: false, latencyMs: 850 }
});
```
*A blinking `β` cursor is natively rendered while streaming is active!*
---
## β³ Promise API
Manage asynchronous workflows beautifully.
```javascript
NotifyX.promise(
fetch('/api/user/profile'),
{
loading: 'Loading profile...',
success: 'Profile loaded!',
error: 'Failed to fetch profile'
}
);
```
---
## π¨ Zero-Dependency Theme System
NotifyX v4 ships with 6 distinct, highly-polished themes powered by Vanilla CSS Custom Propertiesβno Tailwind required.
- `auto` (Default) β Adapts to OS preference
- `light` β Pristine, modern white
- `dark` β Deep, sleek dark mode
- `glass` β Premium frosted glassmorphism
- `minimal` β Flat, pure content focus
- `brutal` β Monochrome, monospace brutalist
**Usage:**
```javascript
// Globally
NotifyX.setTheme('glass');
// Per-Toast
NotifyX.success('Task complete', { theme: 'brutal' });
```
---
## π¬ Animation Engine
Powered by the **Web Animations API** for buttery-smooth 60fps rendering, bypassing Main Thread blocking.
- `spring` (Default) β Bouncy, physical, lively
- `slide` β Smooth directional translation
- `bloom` β Elegant scale and fade
- `flip` β 3D spatial rotation
- `fade` β Simple opacity transition
```javascript
NotifyX.info('System update', { animation: 'bloom' });
```
---
## π οΈ Advanced Subsystem Accessors
Because NotifyX v4 is built on a modular architecture, we expose the underlying subsystems directly on the `NotifyX` object for advanced control:
- **`NotifyX.queue`**: Access the Min-Heap priority queue (`ToastQueue`) instance. Manage overflow, peak queued states, or manually flush items.
- **`NotifyX.animation`**: Access the `AnimationEngine` directly. Hook into the Web Animations API (WAAPI) engine to apply `staggerEnter`, `pulse`, or `shake` animations to your own UI elements.
- **`NotifyX.stream_bridge`**: Access the `StreamBridge` utility. Use its `fromIterable` and `pipe` helpers to map arbitrary LLM data streams directly into DOM nodes.
---
## βοΈ Global Configuration
```javascript
NotifyX.configure({
theme: 'glass',
animation: 'spring',
position: 'top-right',
duration: 4000,
maxToasts: 3,
pauseOnHover: true
});
```
---