1.1.0 • Published 1 year ago

@sirenapp/react-native-inbox v1.1.0

Weekly downloads
-
License
MIT
Repository
github
Last release
1 year ago

Siren React Native Inbox

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.

1. Installation

You can install the react sdk from npm

npm install @sirenapp/react-native-inbox

or from yarn

yarn add @sirenapp/react-native-inbox

2. Configuration

2.1 Initialization

Initialize the sdk with 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',
};

<SirenProvider config={config}>
  {/* Your app components */}
</SirenProvider>

2.2 Configure notification icon

Once the provider is configured, next step is to configure the 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 />

Props for notification icon

Below are optional props available for the icon component:

PropDescriptionTypeDefault value
themeObject for custom themesTheme{}
customStylesObject for custom stylingCustomStyleProps{}
notificationIconOption to use custom notification iconJSX Elementnull
darkModeToggle to enable dark modebooleanfalse
onErrorCallback for handling errors(error: SirenErrorType)=> voidnull
onPressCustom click handler for notification icon()=> voidnull
disabledToggle to disable click on iconbooleanfalse
hideBadgeToggle to hide unviewed count badgebooleanfalse

Theme customization

Here are the available theme options:

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

    type ThemeProps = {
        badgeStyle?: {
            color?: string;
            textColor?: string;
        };
    }

Style customization

Here are the custom style options for the notification icon:

    type CustomStyleProps = {
        notificationIcon?: {
          size?: number,
        };
        badgeStyle?: {
            size?: number;
            textSize?: number;    
            top?: number;
            right?: number;
        };
    }

2.3. Configure notification inbox

Inbox is a paginated list view for displaying notifications.

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

<SirenInbox />

Props for the notification inbox

Below are optional props available for the inbox component:

PropDescriptionTypeDefault value
themeObject for custom themesTheme{}
customStylesObject for custom stylingCustomStyleProps{}
darkModeToggle to enable dark modebooleanfalse
itemsPerFetchNumber of notifications fetch per api request (have a max cap of 50)number20
cardPropsProps for customizing the cardCardProps{ hideAvatar: false, disableAutoMarkAsRead: false, hideDelete: false, deleteIcon: JSX.Element, onAvatarClick: ()=> null, hideMediaThumbnailL: false, onMediaThumbnailClick: ()=> null}
customCardFunction for rendering custom card(notification)=> JSX Elementnull
onCardClickCustom click handler for card(notification)=> void()=>null
listEmptyComponentCustom component for empty listJSX Elementnull
headerPropsProps for customizing the headerHeaderProps{ title: "Notifications", hideHeader: false, hideClearAll: false, customHeader: null, showBackButton:false, backButton: null, onBackPress: ()=> null }
customFooterCustom footer componentJSX Elementnull
customLoaderCustom component to display the initial loading stateJSX Elementnull
customErrorWindowCustom error windowJSX Elementnull
onErrorCallback for handling errors(error: SirenErrorType)=> voidnull

Theme customization

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;
        };
        windowHeader?: {
            background?: string;
            titleColor?: string;
            headerActionColor?: string;
            borderColor?: string;
        };
        windowContainer?: {
            background?: string;
        };
        notificationCard?: {
            borderColor?: string;
            background?: string;
            titleColor?: string;
            subTitleColor?: string;
            descriptionColor?: string;
        };
    }

Style options

Here are the custom style options for the notification inbox:

    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;
    };

3. Hooks

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

FunctionsParametersTypeDescription
markAsReadByDatestartDateISO date stringSets the read status of notifications to true until the given date
markAsReadByIdidstringSet read status of a notification to true
deleteByIdidstringDelete a notification by id
deleteByDatestartDateISO date stringDelete all notifications until given date
markAllAsViewedstartDateISO date stringSets the viewed status of notifications to true until the given date

Example

Here's a basic example to help you get started

import React from 'react';
import {SafeAreaView} from 'react-native';
import {SirenInbox,SirenInboxIcon,SirenProvider} 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>
  );
}

export default App;

function MyContainer(): React.JSX.Element {

  return (
    <View>
      <SirenInboxIcon
        darkMode={false}
      />
      <SirenInbox
        hideHeader={false}
        darkMode={false}
        cardProps={{hideAvatar: false, disableAutoMarkAsRead: false}}
      />
    </View>
  );
}

export default MyContainer;
1.1.0

1 year ago

1.0.0

1 year ago