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.
You can install the react sdk from npm
npm install @sirenapp/react-inboxor from yarn
yarn add @sirenapp/react-inbox- React v16.8+
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",
};
<SirenProvider config={config}>{/* Your app components */}</SirenProvider>;Once the provider is configured, next step is to configure the notification inbox
Inbox is a paginated list view for displaying notifications.
import { SirenInbox } from "@sirenapp/react-inbox";
<SirenInbox />Below are optional props available for the inbox component:
| 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 | false | |
| tabProps | Props for customizing tab. tabs - List of tab items. activeTab - Active tab index. |
tabProps | { tabs: [ { key: 'all', title: 'All' }, { key: 'unread', title: 'Unread' } ],activeTab: 0} |
| itemsPerFetch | Number of notifications fetch per api request (have a max cap of 50) | number | 20 |
| windowViewOnly | Toggle to enable fit-to-screen window or modal view | boolean | false |
| notificationIcon | Option to use custom notification Icon | JSX Element | null |
| headerProps | Props for customizing the header. title - Title of the notification inbox hideHeader - Toggle to hide or show the header section. hideClearAll - Toggle to hide or show the clear all button. customHeader - Custom header component. |
HeaderProps | { title: 'Notifications', hideHeader: false, hideClearAll: false, customHeader: null } |
| cardProps | Props for customizing the notification cards. hideDelete - Toggle to hide or show delete icon hideAvatar - Toggle to hide or show the avatar. hideMediaThumbnail - Toggle to hide or show thumbnail image disableAutoMarkAsRead - Toggle to disable or enable the markAsReadById functionality on card click. deleteIcon - Custom delete icon onAvatarClick - Custom click handler for avatar onMediaThumbnailClick - Custom click handler for media thumbnail |
CardProps | { hideDelete: false, hideAvatar: false, disableAutoMarkAsRead: false, hideMediaThumbnail: false, deleteIcon: null, onAvatarClick: ()=>null, onMediaThumbnailClick: () => null } |
| 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 | JSX Element | null |
| onError | Callback for handling errors | (error: SirenErrorType)=> void | null |
Here are the available theme options:
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
};
};Here are the custom style options for the notification inbox
Please note that the badgeStyle, window shadow and border props are only applicable for modal view
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
};
} type CardProps = {
hideDelete?: boolean,
hideAvatar?: boolean,
hideMediaThumbnail?: boolean,
disableAutoMarkAsRead?: boolean,
deleteIcon?: JSX.Element,
onAvatarClick?: () => void,
onMediaThumbnailClick?: () => void,
}; type InboxHeaderProps = {
title?: string,
hideHeader?: boolean,
hideClearAll?: boolean,
customHeader?: JSX.Element | null,
};useSiren is a hook that provides utility functions for modifying notifications.
import { useSiren } from "@sirenapp/react-inbox";
function MyComponent() {
const {
markAsReadById,
} = useSiren();
function handleMarkAsRead(id) {
markAsReadById(id);
}
return {
/* Your component logic */
};
}| Functions | Parameters | Type | Description |
|---|---|---|---|
| markAsReadByDate | options | { startDate: ISO date string, isRead?: boolean } |
Updates the read status of notifications. startDate- To set the read status of notifications up to the specified date. isRead- Filters notifications based on their read status. |
| markAsReadById | id | string | Set read status of a notification to true |
| deleteById | id | string | Delete a notification by id |
| deleteByDate | options | { startDate: ISO date string, isRead?: boolean } |
Delete all notifications until given start date. startDate- To specify the date until which notifications are deleted. isRead- Filters notifications based on their read status. |
| markAllAsViewed | untilDate | ISO date string | Sets the viewed status of notifications to true until the given date |
Here's a basic example to help you get started
import React from "react";
import { SirenInbox, SirenProvider } from "@sirenapp/react-inbox";
function App(): React.JSX.Element {
const config = {
userToken: "your_user_token",
recipientId: "your_recipient_id",
};
return (
<SirenProvider config={config}>
<MyContainer />
</SirenProvider>
);
}
export default App;
export function MyContainer(): React.JSX.Element {
return (
<div>
<SirenInbox
headerProps={
title: "Notifications",
hideHeader: false
}
darkMode={false}
cardProps={{
hideDelete: false,
hideAvatar: false,
disableAutoMarkAsRead: false,
deleteIcon: null,
onAvatarClick: () => null,
}}
/>
</div>
);
}