React Package Documentation

React components and hooks for integrating notifications into your React applications with ease. This package provides seamless integration with the unified notification service.

Installation

npm install @sparkstrand/notifications-react

This package requires @sparkstrand/notifications-core as a peer dependency and integrates with the unified notification service.

Setting Up Your App

App Registration

Before using notifications, your app must register with the notification service using your own provider API keys. This ensures complete isolation from other applications.

// In your server auth route
import { NotificationClient } from '@sparkstrand/notifications-core';

const notificationClient = new NotificationClient({
  appId: process.env.SPARKSTRAND_APP_ID!,
  apiKey: process.env.SPARKSTRAND_API_KEY!,
});

const response = await notificationClient.login('user-123', {
  email: 'user@example.com',
  name: 'User Name',
});

Provider Configuration

Each app manages its own provider credentials:

  • • Novu: For push notifications, in-app notifications, and multi-channel delivery
  • • Resend: For direct email delivery with custom templates
  • • Twilio: For SMS notifications (when implemented)
  • • Custom providers: Add your own notification providers

Key Features

  • • Unified Service Integration: Seamless integration with the notification service
  • • React Hooks: Easy-to-use hooks for notification management
  • • Real-time Updates: Automatic notification updates and real-time delivery status
  • • TypeScript Support: Full type safety and IntelliSense
  • • Customizable Components: Flexible notification components with theming support
  • • Provider Fallback: Automatic fallback to alternative providers if primary fails
  • • Performance Optimized: Efficient rendering and minimal re-renders

Core Components

NotificationCenter

Main notification display component that shows all notifications for the current user.

<NotificationCenter
  maxNotifications={5}
  showUnreadBadge
  onNotificationClick={handleClick}
/>

NotificationBadge

Unread notification counter that can be placed anywhere in your app.

<NotificationBadge
  count={unreadCount}
  maxCount={99}
  variant="dot"
/>

NotificationItem

Individual notification display component with customizable styling.

<NotificationItem
  notification={notification}
  onMarkAsRead={handleMarkAsRead}
  onDelete={handleDelete}
/>

NotificationList

Scrollable list of notifications with pagination and filtering support.

<NotificationList
  notifications={notifications}
  pageSize={20}
  onLoadMore={loadMore}
/>

React Hooks

useNotifications

Main hook for managing notifications in your React components.

const {
  notifications,
  unreadCount,
  markAsRead,
  deleteNotification,
  refreshNotifications
} = useNotifications();

Configuring authentication

Provide `appInstanceUrl` for default auth, or `loginFunction` when you need custom token retrieval.

const notifications = useNotifications({
  appInstanceUrl: 'https://your-app.com',
  enablePolling: true,
  pollInterval: 30000,
});

useNotifications (full return shape)

The React package currently exports `useNotifications` for inbox and state management.

const {
  notifications,
  unreadCount,
  isLoading,
  error,
  markAsRead,
  markAllAsRead,
  fetchNotifications,
  fetchNotification,
  deleteNotification,
  refreshNotifications,
  clearError,
} = useNotifications({ appInstanceUrl: 'https://your-app.com' });

Usage Examples

Basic Setup

import {useNotifications, NotificationCenter} from
  '@sparkstrand/notifications-react';

function App() {
  const {notifications, unreadCount} = useNotifications();

  return (
    <div>
      <NotificationBadge count={unreadCount} />
      <NotificationCenter />
      <YourApp />
    </div>
  );
}

Sending Notifications

import { NotificationClient } from '@sparkstrand/notifications-core';

const notificationClient = new NotificationClient({
  appId: process.env.SPARKSTRAND_APP_ID!,
  apiKey: process.env.SPARKSTRAND_API_KEY!,
});

await notificationClient.send({
  title: 'Welcome!',
  message: 'Thanks for joining our platform',
  type: 'INFO',
  recipientId: 'user-123',
  channels: ['in_app'],
  pushTitle: 'Welcome!',
  pushBody: 'Thanks for joining our platform',
});

Custom Notification Component

function CustomNotification({notification}) {
  const {markAsRead, deleteNotification} = useNotifications();

  return (
    <div className="custom-notification">
      <h3>{notification.title}</h3>
      <p>{notification.content}</p>
      <div className="actions">
        <button onClick={() => markAsRead(notification.id)}>
          Mark Read
        </button>
        <button onClick={() => deleteNotification(notification.id)}>
          Delete
        </button>
      </div>
    </div>
  );
}

Customization

Theming & Styling

All components support extensive customization through CSS classes and theme props:

  • • CSS Custom Properties: Customize colors, spacing, and typography
  • • Theme Props: Pass custom themes to components
  • • CSS Modules: Use CSS modules for component-specific styling
  • • Styled Components: Integrate with styled-components or emotion
  • • Tailwind CSS: Full Tailwind CSS support with custom classes

Best Practices

  • • Register early: Register your app during application startup
  • • Use hooks appropriately: Choose the right hook for your use case
  • • Handle loading states: Show loading indicators while notifications are being fetched
  • • Error boundaries: Wrap notification components in error boundaries
  • • Performance optimization: Use React.memo for notification components when appropriate
  • • Accessibility: Ensure notification components are accessible to screen readers
  • • Testing: Test notification components with different data and states