react-simple-notify

DEMO

React Simple Notify

A lightweight, flexible, and SSR-safe notification library for React applications.

Features

• 🚀 Lightweight - Minimal bundle size
• 🎨 Customizable - Full control over styling and animations
• ⚡ SSR-Safe - Works with Next.js, Remix, and other SSR frameworks
• 📦 TypeScript - Full type safety out of the box
• 🎭 Flexible Positioning - 6 built-in positions
• ⏱️ Auto-dismiss - Configurable duration or persistent notifications

Installation

npm install react-simple-notify
# or
yarn add react-simple-notify
# or
pnpm add react-simple-notify

Quick Start

Basic Usage

import { notify } from 'react-simple-notify';
import { NotifyContainers } from 'react-simple-notify/client';

function App() {
  const showNotification = () => {
    notify.open({
      render: ({ onClose }) => (
        <div className="notification">
          <p>This is a notification!</p>
          <button onClick={onClose}>Close</button>
        </div>
      ),
    });
  };

  return (
    <>
      <button onClick={showNotification}>Show Notification</button>
      <NotifyContainers />
    </>
  );
}

export default App;

API Reference

notify.open(options)

Opens a new notification.

Parameters

Parameter	Type	Required	Default	Description
render	Function	Yes	-	Render function that returns notification content. Receives NotifyRenderArgs as argument.
id	string	No	Auto-generated	Unique identifier for the notification.
duration	number	No	3500	Time in milliseconds before auto-close. Set to 0 for persistent notifications.
alignment	NotifyAlignment	No	bottomLeft	Position on screen where notification appears.
variant	string	No	-	Custom variant identifier for styling purposes.

Render Function Arguments (NotifyRenderArgs)

Your render function receives an object with:

{
  id: string;              // Notification ID
  duration: number;        // Duration in ms
  alignment: NotifyAlignment; // Position
  variant?: string;        // Custom variant (if provided)
  onClose: () => void;     // Function to close this notification
}

Example

notify.open({
  duration: 5000,
  alignment: NotifyAlignment.topRight,
  variant: 'success',
  render: ({ onClose, variant }) => (
    <div className={`notification ${variant}`}>
      <span>Operation completed successfully!</span>
      <button onClick={onClose}>✕</button>
    </div>
  ),
});

notify.close(id)

Closes a specific notification by ID.

const notificationId = 'my-notification';

notify.open({
  id: notificationId,
  render: () => <div>I can be closed programmatically</div>,
});

// Later...
notify.close(notificationId);

notify.closeAll()

Closes all active notifications.

notify.closeAll();

NotifyAlignment

Available positioning options:

enum NotifyAlignment {
  topLeft = 'top-left',
  topRight = 'top-right',
  topCenter = 'top-center',
  bottomLeft = 'bottom-left',
  bottomRight = 'bottom-right',
  bottomCenter = 'bottom-center',
}

Usage:

import { notify, NotifyAlignment } from 'react-simple-notify';

notify.open({
  alignment: NotifyAlignment.topCenter,
  render: () => <div>Notification at top center</div>,
});

Configuration API

config.set(props)

Set global configuration for all notifications.

Parameters

Parameter	Type	Default	Description
alignment	NotifyAlignment	bottomLeft	Default position for all notifications.
reverse	boolean	false	If true, new notifications appear at the bottom of the stack.
notifyComponent	React.ComponentType	Fragment	Wrapper component for notification content.
animationConfig	AnimationConfig	Default animations	Custom enter/exit animations.

Example: Global Configuration

import { config, NotifyAlignment } from 'react-simple-notify';

config.set({
  alignment: NotifyAlignment.topRight,
  reverse: true,
});

Example: Custom Wrapper Component

import { config } from 'react-simple-notify';

const NotificationWrapper = ({ children, variant }) => (
  <div className={`notification-wrapper ${variant}`}>
    {children}
  </div>
);

config.set({
  notifyComponent: NotificationWrapper,
});

// Now all notifications will be wrapped
notify.open({
  variant: 'error',
  render: () => <span>Error occurred!</span>,
});
// Renders: <NotificationWrapper variant="error"><span>Error occurred!</span></NotificationWrapper>

config.reset()

Reset configuration to default values.

config.reset();

Styling

CSS Custom Properties

Customize container spacing using CSS variables:

:root {
  --rsn-container-padding: 16px;  /* Space from screen edges */
  --rsn-container-gap: 12px;      /* Space between notifications */
}

Styling Notifications

Style your notification content using regular CSS:

// Component
notify.open({
  render: () => (
    <div className="my-notification">
      <span>Custom styled notification</span>
    </div>
  ),
});

/* Styles */
.my-notification {
  background: white;
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

Custom Animations

Animation Configuration

Override default animations using animationConfig:

import { config } from 'react-simple-notify';

config.set({
  animationConfig: {
    enter: {
      duration: 300,
      easing: 'ease-out',
      keyframes: ({ alignment }) => [
        { opacity: 0, transform: 'translateY(-100%)' },
        { opacity: 1, transform: 'translateY(0)' },
      ],
    },
    exit: {
      duration: 200,
      easing: 'ease-in',
      keyframes: ({ node }) => [
        { opacity: 1, transform: 'scale(1)' },
        { opacity: 0, transform: 'scale(0.8)' },
      ],
    },
  },
});

Animation API

Each animation stage (enter/exit) accepts:

Property	Type	Description
duration	number	Animation duration in milliseconds.
easing	string	CSS easing function (e.g., 'ease-in-out', 'cubic-bezier(0.4, 0, 0.2, 1)').
keyframes	Function	Function returning array of keyframes. Receives { node, alignment }.

SSR Support

The library is fully SSR-compatible. The core API can be imported in server environments without causing errors.

Next.js App Router

// app/providers.tsx
'use client';

import { NotifyContainers } from 'react-simple-notify/client';

export function Providers({ children }) {
  return (
    <>
      {children}
      <NotifyContainers />
    </>
  );
}

// app/layout.tsx
import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

// Anywhere in your app (client or server components)
import { notify } from 'react-simple-notify';

// This is safe to call even on the server
// (it will simply no-op in non-browser environments)
function handleError() {
  notify.open({
    render: () => <div>An error occurred</div>,
  });
}

Remix

// app/root.tsx
import { NotifyContainers } from 'react-simple-notify/client';

export default function App() {
  return (
    <html>
      <head />
      <body>
        <Outlet />
        <NotifyContainers />
      </body>
    </html>
  );
}

Testing

The library is test-friendly and won't crash when imported in Node.js environments like Vitest or Jest:

// my-component.test.ts
import { notify } from 'react-simple-notify';

test('notification logic', () => {
  // This won't crash even though there's no DOM
  notify.open({
    render: () => <div>Test notification</div>,
  });

  // Test your logic...
});

Note: Notifications won't actually render in test environments (no DOM), but the API calls won't throw errors.

Advanced Examples

Persistent Notification

notify.open({
  duration: 0, // Never auto-close
  render: ({ onClose }) => (
    <div className="important-alert">
      <h3>Action Required</h3>
      <p>Please review your settings.</p>
      <button onClick={onClose}>Dismiss</button>
    </div>
  ),
});

Success/Error Variants

const showSuccess = (message) => {
  notify.open({
    variant: 'success',
    render: () => (
      <div className="notification success">
        ✓ {message}
      </div>
    ),
  });
};

const showError = (message) => {
  notify.open({
    variant: 'error',
    duration: 0, // Errors stay until dismissed
    render: ({ onClose }) => (
      <div className="notification error">
        ✕ {message}
        <button onClick={onClose}>Close</button>
      </div>
    ),
  });
};

Programmatic Control

const notificationId = 'loading-notification';

// Show loading notification
notify.open({
  id: notificationId,
  duration: 0,
  render: () => <div>Loading...</div>,
});

// Later, close it and show success
fetch('/api/data')
  .then(() => {
    notify.close(notificationId);
    notify.open({
      render: () => <div>Data loaded successfully!</div>,
    });
  });

TypeScript

Full TypeScript support is included. All types are exported:

import type {
  NotifyRenderArgs,
  NotifyAlignment,
  AnimationConfig,
  ConfigProps
} from 'react-simple-notify';

License

MIT © GruFFix

Links

• Demo
• GitHub