React

Overview

The @sirenapp/react-inbox SDK is a comprehensive and customizable React UI kit for displaying and managing notifications. This documentation provides comprehensive information on how to install, configure, and use the SDK effectively.

Installation

npm install @sirenapp/react-inbox

yarn add @sirenapp/react-inbox

Prerequisites

React v16.8+

Configuration

Initialization

Initialize the SDK with user token and recipient ID. Wrap the provider around your App’s root.

import { SirenProvider } from "@sirenapp/react-inbox";

const config = {
  userToken: "your_user_token",
  recipientId: "your_recipient_id",
};

function App() {
  return (
    <SirenProvider config={config}>
      {/* Your app components */}
    </SirenProvider>
  );
}

Configure Notification Inbox

Once the provider is configured, the next step is to set up the notification inbox. The SirenInbox component provides a paginated list view for displaying notifications.

import { SirenInbox } from "@sirenapp/react-inbox";

function NotificationCenter() {
  return <SirenInbox />;
}

Props for the Notification Inbox

Prop	Description	Type	Default Value
`theme`	Object for custom themes	`Theme`	`{}`
`customStyles`	Object for custom styling	`CustomStyle`	`{}`
`loadMoreLabel`	Text shown on the load more component	`string`	`"Load More"`
`hideBadge`	Toggle to hide or show the badge	`boolean`	`false`
`darkMode`	Toggle to enable dark mode	`boolean`	`false`
`hideTab`	Toggle to enable all and unread tabs	`boolean`	`false`
`tabProps`	Props for customizing tabs	`TabProps`	See below
`itemsPerFetch`	Number of notifications per API request (max 50)	`number`	`20`
`windowViewOnly`	Toggle for fit-to-screen window or modal view	`boolean`	`false`
`notificationIcon`	Custom notification icon	`JSX.Element`	`null`
`headerProps`	Props for customizing the header	`HeaderProps`	See below
`cardProps`	Props for customizing notification cards	`CardProps`	See below
`customCard`	Function for rendering custom notification cards	`(notification) => JSX.Element`	`null`
`onCardClick`	Custom click handler for notification cards	`(notification) => void`	`() => null`
`listEmptyComponent`	Custom component for empty notification list	`JSX.Element`	`null`
`customFooter`	Custom footer component	`JSX.Element`	`null`
`customLoader`	Custom loader component	`JSX.Element`	`null`
`loadMoreComponent`	Custom load more component	`JSX.Element`	`null`
`customErrorWindow`	Custom error window component	`JSX.Element`	`null`
`onError`	Error callback function	`(error: SirenErrorType) => void`	`null`

Customization

Customize the appearance of the notification inbox using themes:

Theme Customization

type Theme = {
  dark: ThemeProps,
  light: ThemeProps,
};

type ThemeProps = {
  colors?: {
    primaryColor?: string,
    textColor?: string,
    neutralColor?: string,
    borderColor?: string,
    highlightedCardColor?: string,
    dateColor?: string,
    deleteIcon?: string,
    timerIcon?: string,
    clearAllIcon?: string,
    infiniteLoader?: string,
    windowShadowColor?: string,
  },
  badgeStyle?: {
    color?: string,
    textColor?: string,
  },
  windowHeader?: {
    background?: string,
    titleColor?: string,
    headerActionColor?: string,
  },
  windowContainer?: {
    background?: string,
  },
  customCard?: {
    borderColor?: string,
    background?: string,
    titleColor?: string,
    subtitleColor?: string,
    descriptionColor?: string,
  },
  loadMoreButton?: {
    color?: string,
    background?: string,
  },
  tabs?: {
    containerBackgroundColor?: string,
    activeTabBackgroundColor?: string,
    activeTabTextColor?: string,
    inactiveTabTextColor?: string,
    indicatorColor?: string,
    borderColor?: string,
    inactiveTabBackgroundColor?: string
  };
};

Customize the styling of various components:

Style Customization

type CustomStyle = {
  notificationIcon?: {
    size?: number,
  },
  window?: {
    width?: DimensionValue,
    borderRadius?: number,
  },
  windowHeader?: {
    height?: DimensionValue,
    titleFontWeight?: TextStyle["fontWeight"],
    titleSize?: number,
    titlePadding?: number,
    borderWidth?: string,
  },
  windowContainer?: {
    padding?: number,
    contentHeight?: DimensionValue,
  },
  customCard?: {
    padding?: number,
    borderWidth?: number,
    avatarSize?: number,
    titleFontWeight?: TextStyle["fontWeight"],
    titleSize?: number,
    subtitleFontWeight?: TextStyle['fontWeight'],
    subtitleSize?: number,
    descriptionFontWeight?: TextStyle['fontWeight'],
    descriptionSize?: number,
    dateSize?: number,
  },
  loadMoreButton?: {
    fontSize?: number,
    fontWeight?: TextStyle["fontWeight"]
  },
  badgeStyle?: {
    size?: number,
    textSize?: number,
    top?: number,
    right?: number
  },
  deleteIcon?:{
    size?: number
  },
  timerIcon?:{
    size?: number
  },
  clearAllIcon?:{
    size?: number
  },
  tabs?: {
    containerHeight?: number,
    tabPadding?: number,
    activeTabTextSize?: number,
    inactiveTabTextSize?: number,
    activeTabTextWeight?: TextStyle['fontWeight'],
    inactiveTabTextWeight?: TextStyle['fontWeight'],
    indicatorHeight?: number,
    headingGap?: number,
    borderWidth?: number,
    borderRadius?: number,
    paddingY?: number,
    paddingX?: number,
    tabContainerBorderWidth?: number
  };
}

Component Props

CardProps

type CardProps = {
  hideDelete?: boolean,
  hideAvatar?: boolean,
  hideMediaThumbnail?: boolean,
  disableAutoMarkAsRead?: boolean,
  deleteIcon?: JSX.Element,
  onAvatarClick?: () => void,
  onMediaThumbnailClick?: () => void,
};

InboxHeaderProps

type InboxHeaderProps = {
  title?: string,
  hideHeader?: boolean,
  hideClearAll?: boolean,
  customHeader?: JSX.Element | null,
};

Hooks

useSiren

The useSiren hook provides utility functions for modifying notifications:

import { useSiren } from "@sirenapp/react-inbox";

function MyComponent() {
  const {
    markAsReadById,
    markAsReadByDate,
    deleteById,
    deleteByDate,
    markAllAsViewed
  } = useSiren();

  // Example usage
  const handleMarkAsRead = (id) => {
    markAsReadById(id);
  };

  // ... rest of your component
}

useSiren Functions

Function	Parameters	Type	Description
`markAsReadByDate`	`{ startDate: string, isRead?: boolean }`	`object`	Updates read status of notifications up to the specified date
`markAsReadById`	`id: string`	`string`	Sets read status of a notification to true
`deleteById`	`id: string`	`string`	Deletes a notification by ID
`deleteByDate`	`{ startDate: string, isRead?: boolean }`	`object`	Deletes notifications until the given date
`markAllAsViewed`	`untilDate: string`	`string`	Sets the viewed status of notifications to true until the given date

Complete Example

Here’s a complete example of implementing the Siren React Inbox:

import React from "react";
import { SirenInbox, SirenProvider } from "@sirenapp/react-inbox";

// Custom theme
const customTheme = {
  light: {
    colors: {
      primaryColor: "#4f46e5",
      textColor: "#1f2937",
      neutralColor: "#9ca3af",
      borderColor: "#e5e7eb",
      highlightedCardColor: "#f3f4f6",
    },
    windowHeader: {
      background: "#ffffff",
      titleColor: "#111827",
    },
  },
  dark: {
    colors: {
      primaryColor: "#6366f1",
      textColor: "#f9fafb",
      neutralColor: "#9ca3af",
      borderColor: "#374151",
      highlightedCardColor: "#1f2937",
    },
    windowHeader: {
      background: "#111827",
      titleColor: "#f9fafb",
    },
  },
};

// Custom styles
const customStyles = {
  window: {
    width: 400,
    borderRadius: 12,
  },
  windowHeader: {
    height: 60,
    titleSize: 18,
    titleFontWeight: "600",
  },
  customCard: {
    padding: 16,
    borderWidth: 1,
    avatarSize: 40,
    titleSize: 16,
    subtitleSize: 14,
    descriptionSize: 14,
    dateSize: 12,
  },
};

function App() {
  const config = {
    userToken: "your_user_token",
    recipientId: "your_recipient_id",
  };

  return (
    <SirenProvider config={config}>
      <div className="app">
        <h1>My Application</h1>
        <NotificationCenter />
      </div>
    </SirenProvider>
  );
}

function NotificationCenter() {
  return (
    <div className="notification-center">
      <SirenInbox
        theme={customTheme}
        customStyles={customStyles}
        darkMode={false}
        headerProps={{
          title: "Notifications",
          hideHeader: false,
          hideClearAll: false,
        }}
        cardProps={{
          hideDelete: false,
          hideAvatar: false,
          disableAutoMarkAsRead: false,
          onAvatarClick: (notification) => {
            console.log("Avatar clicked:", notification);
          },
        }}
        onCardClick={(notification) => {
          console.log("Notification clicked:", notification);
        }}
        onError={(error) => {
          console.error("Siren Error:", error);
        }}
      />
    </div>
  );
}

export default App;

Backend SDKs

Frontend SDKs

Overview

Installation

Prerequisites

Configuration

Initialization

Configure Notification Inbox

Props for the Notification Inbox

Customization

Component Props

CardProps

InboxHeaderProps

Hooks

useSiren

useSiren Functions

Complete Example

​Overview

​Installation

​Prerequisites

​Configuration

​Initialization

​Configure Notification Inbox

​Props for the Notification Inbox

​Customization

​Component Props

​CardProps

​InboxHeaderProps

​Hooks

​useSiren

​useSiren Functions

​Complete Example

Overview

Installation

Prerequisites

Configuration

Initialization

Configure Notification Inbox

Props for the Notification Inbox

Customization

Component Props

CardProps

InboxHeaderProps

Hooks

useSiren

useSiren Functions

Complete Example