[](https://www.npmjs.com/package/react-simple-notify) [](https://bundlephobia.com/package/react-simple-notify
npm install react-simple-notify
A lightweight, performant notification library for React applications.
- ⚡ Lightning Fast - Optimized performance with minimal re-renders
- 📦 Tiny Bundle - Only ~3.5KB gzipped, zero dependencies
- 🎨 Fully Customizable - Complete control over styling and animations
- 🔧 TypeScript First - Built with TypeScript, full type safety
- 🌐 SSR Compatible - Works with Next.js, Remix, and other SSR frameworks
- ⏸️ Pause on Hover - Auto-dismiss timer pauses when users hover
- 🎯 Smart Positioning - 6 built-in positions with stack management
``bash`
npm install react-simple-notify
`bash`
yarn add react-simple-notify
`bash`
pnpm add react-simple-notify
`jsx
import { notify, NotifyContainers } from 'react-simple-notify';
function App() {
const showNotification = () => {
notify.open({
render: ({ onClose }) => (
Your changes have been saved
return (
<>
);
}
`
Opens a new notification.
#### Options
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| render | (args: NotifyRenderArgs) => ReactNode | Yes | - | Render function that returns notification content |id
| | string | No | Auto-generated | Unique identifier for the notification |duration
| | number | No | 3500 | Time in ms before auto-close. Set to 0 for persistent |alignment
| | NotifyAlignment | No | bottomLeft | Position where notification appears |pauseOnHover
| | boolean | No | false | Pause auto-dismiss timer on hover |data
| | any | No | undefined | Custom data passed to render function |
#### Render Function Arguments
`typescript`
interface NotifyRenderArgs {
id: string; // Notification ID
duration: number; // Duration in ms
alignment: NotifyAlignment; // Position
onClose: () => void; // Function to close this notification
data?: any; // Custom data (if provided)
timeRemaining: number; // Time remaining until auto-close (in ms)
}
#### Example
`jsx
import { notify, NotifyAlignment } from 'react-simple-notify';
notify.open({
alignment: NotifyAlignment.topRight,
duration: 5000,
pauseOnHover: true,
render: ({ onClose }) => (
---
$3
Updates an existing notification by ID.
jsx
const id = notify.open({
duration: 0,
data: { progress: 0 },
render: ({ data }) => (
Loading... {data.progress}%
),
});// Update progress
notify.update(id, { data: { progress: 50 } });
// Update to completion
notify.update(id, {
duration: 3000,
render: () =>
✓ Complete!,
});
`---
$3
Closes a specific notification by ID.
jsx
const id = notify.open({
render: () => I can be closed programmatically,
});// Later...
notify.close(id);
`---
$3
Closes all active notifications.
jsx
notify.closeAll();
`---
$3
Available positioning options:
typescript
enum NotifyAlignment {
topLeft = 'top-left',
topRight = 'top-right',
topCenter = 'top-center',
bottomLeft = 'bottom-left',
bottomRight = 'bottom-right',
bottomCenter = 'bottom-center',
}
`Usage:
jsx
import { notify, NotifyAlignment } from 'react-simple-notify';notify.open({
alignment: NotifyAlignment.topCenter,
render: () =>
Notification at top center,
});
`---
Global Configuration
$3
Set global configuration for all notifications.
#### Options
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
|
| NotifyAlignment | bottomLeft | Default position for all notifications |
| reverse | boolean | false | New notifications appear at bottom of stack |
| notifyComponent | React.ComponentType | Fragment | Wrapper component for notification content |
| animationConfig | AnimationConfig | Default animations | Custom enter/exit animations |
| maxNotifications | number | 0 | Maximum notifications per position (0 = unlimited) |
| pauseOnHover | boolean | false | Global pause on hover setting |#### Example: Basic Configuration
`jsx
import { config, NotifyAlignment } from 'react-simple-notify';config.set({
alignment: NotifyAlignment.topRight,
maxNotifications: 3,
pauseOnHover: true,
});
`#### Example: Custom Wrapper Component
jsx
import { config } from 'react-simple-notify';const NotificationWrapper = ({ children }) => (
{children}
);config.set({
notifyComponent: NotificationWrapper,
});
`---
$3
Reset configuration to default values.
jsx
config.reset();
`---
Styling
$3
Customize container spacing:
css
:root {
--rsn-container-padding: 16px; / Space from screen edges /
--rsn-container-gap: 12px; / Space between notifications /
}
`$3
Style your notifications with regular CSS:
jsx
notify.open({
render: () => (
Custom styled notification
),
});
`css
.my-notification {
background: white;
padding: 16px;
border-radius: 8px;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}
`---
Custom Animations
Override default animations:
jsx
import { config } from 'react-simple-notify';config.set({
animationConfig: {
enter: {
duration: 300,
easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
keyframes: ({ alignment }) => [
{ opacity: 0, transform: 'translateY(-20px)' },
{ opacity: 1, transform: 'translateY(0)' },
],
},
exit: {
duration: 200,
easing: 'ease-in',
keyframes: () => [
{ opacity: 1, transform: 'scale(1)' },
{ opacity: 0, transform: 'scale(0.8)' },
],
},
},
});
`$3
| Property | Type | Description |
|----------|------|-------------|
|
| number | Animation duration in milliseconds |
| easing | string | CSS easing function |
| keyframes | (args) => Keyframe[] | Function returning keyframes array |---
Advanced Examples
$3
`jsx
const showProgress = () => {
let progress = 0; const id = notify.open({
duration: 0,
data: { progress: 0 },
render: ({ data }) => (
Uploading...
${data.progress}% }} />
{data.progress}%
),
}); const interval = setInterval(() => {
progress += 10;
if (progress > 100) {
clearInterval(interval);
notify.update(id, {
duration: 3000,
render: () => (
✓ Upload Complete!
),
});
} else {
notify.update(id, { data: { progress } });
}
}, 300);
};
`$3
jsx
notify.open({
duration: 0, // Never auto-close
pauseOnHover: false,
render: ({ onClose }) => (
⚠ Action Required
Please review your settings
),
});
`$3
jsx
notify.open({
duration: 5000,
pauseOnHover: true,
render: ({ onClose, timeRemaining, duration }) => {
const progress = ((duration - timeRemaining) / duration) * 100; return (
Auto-closing notification
This will close in {Math.ceil(timeRemaining / 1000)}s
style={{ width: ${progress}% }}
/>
);
},
});
`$3
jsx
const saveData = async () => {
const id = notify.open({
duration: 0,
render: () => Saving...,
}); try {
await fetch('/api/save', { method: 'POST' });
notify.close(id);
notify.open({
render: () =>
✓ Saved successfully!,
});
} catch (error) {
notify.update(id, {
duration: 0,
render: ({ onClose }) => (
✕ Failed to save
),
});
}
};
`$3
jsx
import { config } from 'react-simple-notify';config.set({
maxNotifications: 3, // Only 3 visible at once per position
});
// Older notifications are automatically removed
for (let i = 0; i < 10; i++) {
notify.open({
render: () =>
Notification {i + 1},
});
}
// Only the last 3 will be visible
`---
TypeScript
Full TypeScript support included. All types are exported:
typescript
import type {
NotifyRenderArgs,
NotifyOptions,
NotifyAlignment,
AnimationConfig,
ConfigProps,
} from 'react-simple-notify';
``---
Browser Support
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
---
License
MIT © GruFFix
---
Links