Why simple-react-notifications?

Many React apps need fast, keyboard-friendly, and accessible toast messages without the overhead of a huge UI library. simple-react-notifications focuses on the essentials: provider-based state, a small API surface, and render-time customization so you can control visuals and behavior with CSS or a custom renderer.

Because it uses a provider + hooks pattern, state for toasts is scoped and predictable. That means easier testing, server-side rendering friendliness (where applicable), and simple integration with contexts such as theming or localization. You get programmatic control to show, update, or dismiss notifications from anywhere in your component tree.

Performance is another reason: small bundle footprint, no virtual DOM-heavy animations unless you add them, and the ability to configure timeouts and maximum visible toasts. If you’re building a product UI or admin tool and want fast feedback messages, this pattern fits well.

Installation and quick start

To get started, install the package with npm or yarn. This example assumes the package name simple-react-notifications (adjust if your project uses a scoped or forked package).

// npm
npm install simple-react-notifications

// or yarn
yarn add simple-react-notifications
  

Next, wrap your app with the notifications provider. The provider establishes a place where toasts live, and exposes hooks to create and manage messages.

import React from 'react';
import { NotificationsProvider } from 'simple-react-notifications';
import App from './App';

export default function Root() {
  return (
    <NotificationsProvider>
      <App />
    </NotificationsProvider>
  );
}
  

From any component, call the hook to push a toast. The API is intentionally small: show a toast with a message, optional type (success/error/info/warn), and optional options like duration or onClose.

import React from 'react';
import { useNotifications } from 'simple-react-notifications';

export default function SaveButton() {
  const { notify } = useNotifications();

  async function handleSave() {
    try {
      // ... save logic
      notify('Saved successfully', { type: 'success', timeout: 3000 });
    } catch (err) {
      notify('Save failed', { type: 'error' });
    }
  }

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

Core concepts and API you need to know

At runtime you’ll mainly interact with three concepts: the Notifications Provider, the hook that exposes a show/notify method, and the individual toast options. The provider mounts a container in the DOM and manages a queue or stack of toasts so you control max visible items and placement.

The hook (often named useNotifications or useNotification) returns functions to show and dismiss toasts. Basic function signature patterns look like: notify(message, { type, timeout, id, action }). You can store the returned id to update or remove that toast programmatically.

Provider props typically let you define defaults such as position (top-right, bottom-left), default timeout, maximum concurrent toasts, and a custom renderer callback for custom UI. If you need to display React nodes inside toasts (buttons, links), confirm the library supports JSX content or a render prop to avoid string-only limitations.

Examples: common use cases

Quick success/error toasts after network operations are the most common. Because the call is synchronous from the UI point-of-view (you call notify after promise resolution), the UX is straightforward and predictable. Use short timeouts for transient confirmations and longer ones for important errors that need attention.

Actionable toasts (e.g., „Undo” after deleting) are supported by rendering custom content or passing an action callback. Keep accessibility in mind: ensure action buttons are keyboard reachable and the toast uses role=”status” for non-interruptive messages or role=”alert” for urgent errors.

Here’s an example of a toast with an action button inside (JSX content as message):

notify(
  <div>
    File uploaded
    <button onClick={handleUndo}>Undo</button>
  </div>,
  { type: 'info', timeout: 5000 }
);
  

Customization and accessibility

Visual customization is usually done via CSS classes or a custom renderer prop. Prefer CSS variables or BEM-style class names so you can theme toasts without editing library internals. If animations are important, use CSS transitions or a lightweight animation library — but add prefers-reduced-motion detection to respect user preferences.

Accessibility should not be an afterthought. Use ARIA roles: role=”status” for non-blocking info, role=”alert” for urgent errors, and ensure toasts are announced by screen readers. Focus should not be stolen from form fields; instead, provide ARIA-live polite for ephemeral messages.

Keyboard interactions: allow users to dismiss toasts with Escape, and ensure action buttons are reachable via Tab. If toasts are interactive, make them focusable with tabindex=”0″ and manage focus on open if the toast requires immediate attention.

Troubleshooting and best practices

Common issues: toasts stacking awkwardly (tune max visible and container spacing), duplicate messages (debounce or dedupe by id), or missing announcements (ensure ARIA-live regions are present). If your toast library mounts outside your theme context, pass theme via provider props or wrap the provider inside your theme provider.

For server-rendered apps, render the provider only on the client to avoid DOM mismatches, or ensure the provider’s container is consistent between server and client. If you rely on timeouts, be careful with background tabs — browsers throttle timers in inactive tabs which may delay automatic dismissal.

Best practice checklist: set sensible defaults (3s success, 6–8s errors), provide action buttons for undoable operations, avoid excessive toasts during bulk operations, and log errors to a monitoring service rather than repeatedly notifying users of the same failure.

Integration links and further reading

Official React docs on component patterns and hooks are a great companion when integrating notification hooks: React Docs.

For a step-by-step tutorial and example build using this library, see the community walkthrough: simple-react-notifications tutorial.

If you need the package page for installation and versioning, check the npm listing: simple-react-notifications on npm.

FAQ

Semantic core (keyword clusters)