React SDK (Front-End)
The React SDK is mainly used for displaying In-App Notifications and allowing users to see and change their Notification Preferences.
Setup
- Package Manager
- Install the react package:
npm install @notificationapi/react #--legacy-peer-deps
# yarn add @notificationapi/react
# pnpm add @notificationapi/react
If you experience a React version conflict during package installation, try adding --force
or --legacy-peer-deps
to the end of your install command.
- Import and use our provider in your top-level components/routers:
import { NotificationAPIProvider } from '@notificationapi/react';
<App>
<NotificationAPIProvider
userId="abcd-1234" // logged in userId
clientId="abc123" // your clientId found on the dashboard
>
<!-- your protected routes -->
</NotificationAPIProvider>
</App>;
In-App Notification Components
Popup
Click this 👉<NotificationPopup />
Our popup component opens up to display your inbox for in-app notifications. This gives users a small interface for accessing their notifications without taking up screen space. Especially useful for mobile apps.
All notifications are displayed here, and each notification comes with buttons to mark notifications as "seen" or "archived". Additionally, the top right of the inbox contains features for setting user preferences and marking all notifications as read directlyfrom the inbox. If a notification has redirect, interacting with it will send users to that link or page from within the component.
Popup Launcher
<NotificationLauncher />
The popup launcher adds a button to the corner of the page (similar to chat buttons), that remains in place on your application. This gives users access to their inbox from anywhere on a page, so they don't need to scroll up to an inbox, or visit a dedicated inbox page to read and interact with notifications.
Counter (Standalone)
This is the counter 👉<NotificationCounter />
The counter element displays the number of unread notifications. Features:
- Can count "unopened/unseen" notifications or "unarchived" notifications
- Can be a dot like:
- Many other formatting and positioning customizations available
Counter (on existing elements)
Apply the same counter badge on an existing element to notify users of unread messages.
<NotificationCounter>
<Button>Counter</Button>
</NotificationCounter>
![](/assets/images/elementcounter-f9c234a03681421a3d6c73a4da7b7ef1.png)
Feed
The feed component provides a larger feed for browsing notifications. Notifications within the feed can also be clicked on to direct to links or pages, if any were set within the Notification template.
<NotificationFeed infiniteScrollHeight={300} />
Example:
Notification Preferences Center
Preferences Popup
Our notification preferences popup allows users to set their preferences with your app. The component contains all your templates, and sliders for users to opt-in and out of notifications, and per channel where applicable.
const [preferencesPopupVisibility, setPreferencesPopupVisiblity] = React.useState(false);
<button onClick={() => setPreferencesPopupVisiblity(true)}>
Preferences Popup
</button>
<NotificationPreferencesPopup
open={preferencesPopupVisibility}
onClose={() => {
setPreferencesPopupVisiblity(false);
}}
/>
![](/assets/images/notipreferences-8054c5a8c61f5a79f45262c4b0b1cea5.png)
Preferences Inline
Alternatively, we also offer an inline component for user preferences. Ideal for options & settings pages.
<NotificationPreferencesInline />
Example:
UI Customizations
Customizing the Button
Make our button fit in - or stand out. You can customize our button using the following parameters:
Parameter | Type | Description |
---|---|---|
buttonIconSize | number | Determines the size of the icon used for the button. |
buttonHeight | number | Determines the height of the button. |
buttonWidth | number | Determines the width of the button. |
<NotificationPopup buttonIconSize={30} buttonHeight={50} buttonWidth={50} />
Customizing the Button (Launcher)
The launcher component takes additional parameters, allowing you to better position the button on your app.
Parameter | Type | Description |
---|---|---|
offsetX | number or string | Determine a horizontal offset for your popup launcher. |
offsetY | number or string | Determine a vertical offset for your popup launcher. |
position | string : TOP_LEFT , TOP_RIGHT , BOTTOM_LEFT , BOTTOM_RIGHT | Determine which corner you want the popup launcher to anchor on. |
<NotificationLauncher buttonIconSize={30} offsetX={200} offsetY={100} />
Customizing the Header
You can change the header of your notifications to take your own custom React Component. You can modify the "Notifications" header found in the popup, feed, and launcher.
<NotificationPopup
header={{
title: <>"Notification"</>
}}
/>
Customizing the Popup
Customize out popup to be the right fit for your app. Our Popup can be customized using these parameters:
Parameter | Type | Description |
---|---|---|
count | ReactNode["count"] | Modify the appearance of the count on your popup. Behaves similarly to the Counter. |
filter | string : ALL , UNARCHIVED | Filter which notifications appear. Set to ALL by default. |
imageShape | string : circle , square | Determines the shape of images in the popup feed. Set to circle by default. |
pagePosition | string : top , bottom | Determines whether the popup will render page buttons at the top or bottom of the component. Set to top by default. |
pageSize | number | Requires pagination set to PAGINATED . Determines the amount of notifications shown per page. |
pagination | string : INFINITE_SCROLL ,PAGINATED | Choose between a single page or multiple pages for your inbox. Set to INFINITE_SCROLL by default |
renderers | object : {notification: NotificationProps["renderer"], NotificationExtra["extraRenderer"] | Allows you to render custom & additional content. |
style | Record<SemanticDOM, CSSProperties> | Pass in your styles to match our popup with your design |
unreadBadgeProps | ReactNode | Modify the unread badge. Behaves similarly to the Counter. |
<NotificationPopup
imageShape="circle"
pagination="PAGINATED"
pageSize={4}
pagePosition="bottom"
/>
Customizing the Feed
Customize the feed using these parameters:
Parameter | Type | Description |
---|---|---|
filter | ReactNode | Filter the notifications that appear in your feed using a custom component. |
header | ReactNode | Pass in a custom React component as your header. |
imageShape | string : circle , square | Render images with the feed in a circle or square. Set to circle by default. |
infiniteScrollHeight | number | Determine a height for the feed component. |
pagePosition | string : bottom , top | Set a location for the page buttons. Requires pagination to be set to PAGINATED . Set to top by default. |
pageSize | number | Adjust the number of notifications displayed per page. Requires pagination to be set to PAGINATED . |
pagination | string: INFINITE_SCROLL , PAGINATED | Determines whether your feed is paginated, or one page for all notifications. Set to PAGINATED by default. |
renderers | object : { notification: NotificationProps["renderer"] } | Render additional content within your feed. |
style | Record<SemanticDOM, CSSProperties> | Pass in your styles to match our feed with your design. |
<NotificationFeed
pagination="PAGINATED"
pageSize={6}
pagePosition="bottom"
infiniteScrollHeight={300}
/>
Unread Badge
You can customize the unread badge using these parameters and features:
Parameter | Type | Description |
---|---|---|
color | string : blue , cyan , gold , green , lime , magenta , orange , pink , purple , red , yellow , volcano , geekblue | Customize the color for your badge icon. |
count | ReactNode | Set a value to display in the badge. |
classNames | Record<SemanticDOM, string/> | Set class names for your badge component. |
dot | boolean | Display a plain dot instead of your counter. |
offset | [number, number] | Set an alternative location for the badge. |
overflowCount | number | Badge displays a + beside your number when notifications exceed that amount. |
showZero | boolean | Show a 0 on the badge when there are no new notifications. |
size | default , small | Modify the size of the unread badge. |
status | success , processing , default , error , warning | Give notifications a colored badge noting message status. |
styles | Record<SemanticDOM, CSSProperties/> | Use Semantic DOM style to modify your badge. |
text | ReactNode | Sets the badge text to status if status has been set. |
title | string | Set hover text for your badge. |
<NotificationCounter
color="lime"
count={(n) => {
return n.notificationId === 'inapp_notifications' && !n.archived;
}}
dot={false}
size="small"
>
<button>Counter</button>
</NotificationCounter>
Pagination
You can use this to set up pages for your feed. Design scrollable, interactive inbox for your users through our component. Your feed can be modified further using these arguments:
Parameter | Type | Description |
---|---|---|
bordered | boolean | Toggle a border for your feed. Set to false by default. |
dataSource | any[] | Set a data source for your feed. |
footer | ReactNode | Render a footer for your feed. |
grid | object | Give your feed grid properties via JSON. |
header | ReactNode | Render a header for your feed. |
itemLayout | horizontal , vertical | Determine the layout of your feed. |
loading | boolean + | Show a loading symbol within the component when fetching your dataSource . False by default. |
loadMore | ReactNode | Render a component to load more data for yuor feed. |
locale | object | i18n text or empty text. |
pagination | boolean , object | Set and modify pagination for your feed. Set to false by default. |
renderItem | (item) => ReactNode | Define a custom list when using dataSource . |
rowKey | keyof X, (item: X) => React.Key | Determine an item's key value. Can be either a unique value or a function that returns a value. |
size | small , default , large | Adjust the size and spacing of your feed. |
split | boolean | Toggle a visual separator for individual notifications in your feed. Set to false by default. |
Logical Customizations
Count
This refers to what notifications are counted in the counters or unread badges. You can use an existing mode or count the notifications by your own custom function:
COUNT_UNOPENED_NOTIFICATIONS
(default): only counts notifications that are never seen/opened. Once the user opens the notification popup, the count will be reset to zero.COUNT_UNARCHIVED_NOTIFICATIONS
: only counts the notifications that are not archived. The count will change when the user marks notifications as archived.- Custom: you can create your own function to count the notifications. The example code below counts notifications that belong to the
welcome_notification
category and are not archived.
<NotificationPopup
count={(n) => {
return n.notificationId === 'welcome_notification' && !n.archived;
}}
/>
Filters
This refers to which notifications are rendered in the pre-existing popup, feed, ... components. You can filter notifications via existing modes or create your own custom function:
ALL
(default): renders all notificationsUNARCHIVED
: renders only notifications that are not archived- Custom: The example code below filters notifications that belong to the
welcome_notification
category and are not archived.
<NotificationPopup
count={(n) => {
return n.notificationId === 'welcome_notification' && !n.archived;
}}
/>
Customizing each Notification
Headless (build your own UI)
You can build your own UI by reading the data inside our React Context object. It includes all our notification objects, users preferences, and functions for updating notification states. You can use these to build any notification UI you need.
Setup
Inside the components wrapped in our NotificationAPIProvider
, you can access the context object using the useNotificationAPIContext
hook:
export const MyComponent: React.FC = () => {
const notificationapi = NotificationAPIProvider.useNotificationAPIContext();
return (
<Button
onClick={() => {
console.log(notificationapi.notifications);
}}
>
Click to log notifications
</Button>
);
};
Accessing notification data
notificationapi.notifications;
Accessing user preferences
notificationapi.preferences;
Updating user preferences
notificationapi.updateDelivery(
notificationId,
channel,
delivery,
subNotificationId?
)
Marking loaded notifications as opened/seen
notificationapi.markAsOpened();
Marking notifications as archived
// to mark all as archived:
notificationapi.markAsArchived('ALL');
// to mark invididual notifications as archived:
notificationapi.markAsArchived(['trackingId1', 'trackingId2']);
Marking a notification as clicked
notificationapi.markAsClicked('trackingId');
Concepts
How does it work?
You trigger the API from the back-end and we store the notification. When users sign into the app, the sdk will pull their notification.
Websocket
We have our own websocket for sending & receiving new notifications. With this websocket, users will automatically receive new notifications without needing to refresh their pages. Since the websocket is automatically in place, developers don't need to do anything to implement this.
In-App Notification Object
The in-app notification object takes several arguments.
Parameter | Type | Description |
---|---|---|
actioned1 | string | Coming soon! Assign a function for button 1 in your template, if a custom button has been assigned. |
actioned2 | string | Coming soon! Assign a function for button 2 in your template, if a custom button has been assigned. |
archived | string | Determines if the notification is considered as archived. Also referred to as "resolved". |
body | ReactNode | Used to add your custom UI to your notification. |
clicked | string | Determines if the notification has been clicked on by the recipient. |
date | string | Using ISO 8607 formatting (YYYY-MM-DD), give your notification a date. |
expDate | number | Give your notification a TTL by passing in a Unix timestamp (in sencods). The notification will expire once the timestamp has passed. |
id | string | Your notification's tracking ID. Not the same as notificationId. |
imageURL | string | Embed an image within your notification. |
notificationId | string | The ID for your notification's template. |
opened | string | Determines if the notification has been opened by the recipient. Notifications are considered opened if rendered onscreen for the recipient. |
parameters | Record<string, unknown> | Mergetags. Give your notification mergetags/props that can pass values into matching mergetags within your notification templates. |
redirectURL | string | Give your notification a link to send users to upon clicking. |
replies | object: { date: string, message: string }[], | Coming soon - Contains user comments/replies to the notification if enabled. |
title | string | A title for your in-app notification. |