​
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

​
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

PropDescriptionTypeDefault Value
themeObject for custom themesTheme{}
customStylesObject for custom stylingCustomStyle{}
loadMoreLabelText shown on the load more componentstring"Load More"
hideBadgeToggle to hide or show the badgebooleanfalse
darkModeToggle to enable dark modebooleanfalse
hideTabToggle to enable all and unread tabsbooleanfalse
tabPropsProps for customizing tabsTabPropsSee below
itemsPerFetchNumber of notifications per API request (max 50)number20
windowViewOnlyToggle for fit-to-screen window or modal viewbooleanfalse
notificationIconCustom notification iconJSX.Elementnull
headerPropsProps for customizing the headerHeaderPropsSee below
cardPropsProps for customizing notification cardsCardPropsSee below
customCardFunction for rendering custom notification cards(notification) => JSX.Elementnull
onCardClickCustom click handler for notification cards(notification) => void() => null
listEmptyComponentCustom component for empty notification listJSX.Elementnull
customFooterCustom footer componentJSX.Elementnull
customLoaderCustom loader componentJSX.Elementnull
loadMoreComponentCustom load more componentJSX.Elementnull
customErrorWindowCustom error window componentJSX.Elementnull
onErrorError callback function(error: SirenErrorType) => voidnull

​
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

FunctionParametersTypeDescription
markAsReadByDate{ startDate: string, isRead?: boolean }objectUpdates read status of notifications up to the specified date
markAsReadByIdid: stringstringSets read status of a notification to true
deleteByIdid: stringstringDeletes a notification by ID
deleteByDate{ startDate: string, isRead?: boolean }objectDeletes notifications until the given date
markAllAsVieweduntilDate: stringstringSets 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;