Overview
The@sirenapp/react-native-inbox SDK is a comprehensive and customizable React Native 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-native-inbox
yarn add @sirenapp/react-native-inbox
Configuration
Initialization
Initialize the SDK with the user token and recipient ID. Wrap the provider around your App’s root.import { SirenProvider } from '@sirenapp/react-native-inbox';
const config = {
userToken: 'your_user_token',
recipientId: 'your_recipient_id',
};
function App() {
return (
<SirenProvider config={config}>
{/* Your app components */}
</SirenProvider>
);
}
Configure Notification Icon
This component consists of a notification icon along with a badge to display the number of unviewed notifications.import { SirenInboxIcon } from '@sirenapp/react-native-inbox';
<SirenInboxIcon />
Icon Props
| Prop | Description | Type | Default |
|---|---|---|---|
theme | Object for custom themes | Theme | {} |
customStyles | Object for custom styling | CustomStyleProps | {} |
notificationIcon | Option to use custom notification icon | JSX.Element | null |
darkMode | Toggle to enable dark mode | boolean | false |
onError | Callback for handling errors | (error: SirenErrorType) => void | null |
onPress | Custom click handler | () => void | null |
disabled | Disable click on icon | boolean | false |
hideBadge | Hide unviewed count badge | boolean | false |
Customization
Theme Customization
type Theme = {
dark: ThemeProps;
light: ThemeProps;
};
type ThemeProps = {
badgeStyle?: {
color?: string;
textColor?: string;
};
};
Style Customization
type CustomStyleProps = {
notificationIcon?: {
size?: number,
};
badgeStyle?: {
size?: number;
textSize?: number;
top?: number;
right?: number;
};
};
Configure Notification Inbox
Inbox is a paginated list view for displaying notifications.import { SirenInbox } from '@sirenapp/react-native-inbox';
<SirenInbox />
Inbox Props
| Prop | Description | Type | Default |
|---|---|---|---|
theme | Object for custom themes | Theme | {} |
customStyles | Object for custom styling | CustomStyleProps | {} |
darkMode | Toggle dark mode | boolean | false |
itemsPerFetch | Notifications per request (max 50) | number | 20 |
cardProps | Card customization | CardProps | See below |
customCard | Custom card renderer | (notification) => JSX.Element | null |
onCardClick | Card click handler | (notification) => void | () => null |
listEmptyComponent | Empty state component | JSX.Element | null |
headerProps | Header customization | HeaderProps | See below |
customFooter | Custom footer component | JSX.Element | null |
customLoader | Custom loading component | JSX.Element | null |
customErrorWindow | Custom error component | JSX.Element | null |
onError | Error handler | (error: SirenErrorType) => void | null |
Customization
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;
};
windowHeader?: {
background?: string;
titleColor?: string;
headerActionColor?: string;
borderColor?: string;
};
windowContainer?: {
background?: string;
};
notificationCard?: {
borderColor?: string;
background?: string;
titleColor?: string;
subTitleColor?: string;
descriptionColor?: string;
};
};
Style Customization
type CustomStyleProps = {
window?: {
width?: DimensionValue;
height?: DimensionValue;
};
windowHeader?: {
height?: number;
titleFontWeight?: TextStyle['fontWeight'];
titleSize?: number;
borderWidth?: string;
titlePadding?: number;
};
windowContainer?: {
padding?: number;
};
notificationCard?: {
padding?: number;
borderWidth?: number;
avatarSize?: number;
titleFontWeight?: TextStyle['fontWeight'];
titleSize?: number;
subtitleFontWeight?: TextStyle['fontWeight'];
subtitleSize?: number;
descriptionFontWeight?: TextStyle['fontWeight'];
descriptionSize?: number;
dateSize?: number;
};
deleteIcon?: {
size?: number;
};
timerIcon?: {
size?: number;
};
clearAllIcon?: {
size?: number;
};
};
CardProps
type CardProps = {
hideAvatar?: boolean;
onAvatarClick?: (notification: NotificationDataType) => void;
disableAutoMarkAsRead?: boolean;
deleteIcon?: JSX.Element;
hideDelete?: boolean;
hideMediaThumbnail?: boolean;
onMediaThumbnailClick?: (notification: NotificationDataType) => void;
};
HeaderProps
type HeaderProps = {
title?: string;
hideHeader?: boolean;
hideClearAll?: boolean;
customHeader?: JSX.Element | null;
showBackButton?: boolean;
backButton?: JSX.Element;
onBackPress?: () => void;
};
Hooks
useSiren
useSiren is a hook that provides utility functions for modifying notifications.
import { useSiren } from '@sirenapp/react-native-inbox';
function MyComponent() {
const { markAsReadById, deleteById } = useSiren();
function handleMarkAsRead(id) {
markAsReadById(id);
}
return (
// Your component logic
);
}
useSiren Functions
| Function | Parameters | Type | Description |
|---|---|---|---|
markAsReadByDate | startDate | string (ISO date) | Marks notifications as read until given date |
markAsReadById | id | string | Marks a notification as read |
deleteById | id | string | Deletes a notification by ID |
deleteByDate | startDate | string (ISO date) | Deletes notifications until given date |
markAllAsViewed | startDate | string (ISO date) | Marks notifications as viewed until given date |
Complete Example
import React from 'react';
import { SafeAreaView, View } from 'react-native';
import {
SirenProvider,
SirenInbox,
SirenInboxIcon,
useSiren
} from '@sirenapp/react-native-inbox';
function App(): React.JSX.Element {
const config = {
userToken: 'your_user_token',
recipientId: 'your_recipient_id',
};
return (
<SirenProvider config={config}>
<MyContainer />
</SirenProvider>
);
}
function MyContainer(): React.JSX.Element {
const [showInbox, setShowInbox] = React.useState(false);
const { markAllAsViewed } = useSiren();
React.useEffect(() => {
// Mark all notifications as viewed when component mounts
markAllAsViewed(new Date().toISOString());
}, []);
return (
<SafeAreaView style={{ flex: 1 }}>
<View style={{ padding: 16 }}>
<SirenInboxIcon
onPress={() => setShowInbox(true)}
darkMode={false}
/>
</View>
{showInbox && (
<SirenInbox
darkMode={false}
headerProps={{
title: 'Notifications',
showBackButton: true,
onBackPress: () => setShowInbox(false)
}}
cardProps={{
hideAvatar: false,
disableAutoMarkAsRead: false
}}
/>
)}
</SafeAreaView>
);
}
export default App;