Skip to main content
CometChatNotificationFeed displays a scrollable notification feed where each item is rendered as a card using @cometchat/cards-react. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically.
Live Preview — interact with the notification feed component.Open in Storybook ↗

Where It Fits

CometChatNotificationFeed is a full-screen component. Drop it into a page or route. It manages its own data fetching, state, and real-time listeners — you just handle navigation callbacks.

Minimal Render

Prerequisites: CometChat SDK initialized with CometChatUIKit.init() and a user logged in. Root CSS class: .cometchat-notification-feed

Filtering Feed Items

Control what loads using custom request builders:

Filter Options

Builder MethodDescription
.setLimit(number)Items per page (default 20, max 100)
.setReadState(state)"read", "unread", or "all"
.setCategory(string)Filter by category label
.setChannelId(string)Filter by channel
.setTags(string[])Filter by tags
.setDateFrom(string)ISO 8601 date lower bound
.setDateTo(string)ISO 8601 date upper bound

Actions and Events

Callback Props

onItemClick

Fires when a feed item card is clicked.

onActionClick

Fires when an interactive element (button, link) inside a card is clicked. The action object contains the action type, parameters, and the element ID that triggered it.

onError

Fires when an internal error occurs (network failure, SDK exception).

onBackPress

Fires when the back button in the header is clicked.

Automatic Behaviors

The component handles these automatically — no manual setup needed:
BehaviorDescription
Real-time updatesNew items appear at the top via WebSocket NotificationFeedListener
Delivery reportingItems are reported as delivered when fetched
Read reportingItems are reported as read when visible in viewport (IntersectionObserver)
Unread count pollingPolls unread count every 30 seconds to update badges
Infinite scrollFetches next page when scrolling near the bottom
Timestamp groupingGroups items as “Today”, “Yesterday”, day name, or date
Category filteringFilter chips row with per-category unread badges
Mark all readHeader button to mark all notifications as read

Customization

View Props

SlotSignatureReplaces
headerViewReactNodeEntire header bar
loadingViewReactNodeLoading state
emptyViewReactNodeEmpty state
errorViewReactNodeError state
itemView(item: NotificationFeedItem) => ReactNodeIndividual feed item rendering

Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:
Available sub-components:
Sub-componentDescriptionPropsFlat API equivalent
RootContext provider and containerAll Root props + children
HeaderHeader bar with title + mark-all-readtitle, showBackButton, onBackPress, childrenheaderView
FilterChipsCategory filter chipschildren
ListScrollable feed listitemViewitemView
ItemIndividual feed itemitem, cardThemeMode, cardThemeOverride
EmptyStateEmpty statechildrenemptyView
ErrorStateError statechildrenerrorView
LoadingStateLoading statechildrenloadingView

CSS Styling

Override design tokens on the component selector:

CSS Classes

ClassDescription
.cometchat-notification-feedRoot container
.cometchat-notification-feed__headerHeader bar
.cometchat-notification-feed__header-titleHeader title text
.cometchat-notification-feed__header-backBack button
.cometchat-notification-feed__mark-all-readMark all read button
.cometchat-notification-feed__chipsFilter chips container
.cometchat-notification-feed__chipIndividual filter chip
.cometchat-notification-feed__chip--activeActive filter chip
.cometchat-notification-feed__chip--inactiveInactive filter chip
.cometchat-notification-feed__chip-badgeChip unread badge
.cometchat-notification-feed__contentScrollable content area
.cometchat-notification-feed__itemFeed item container
.cometchat-notification-feed__item--unreadUnread feed item
.cometchat-notification-feed__unread-indicatorUnread dot indicator
.cometchat-notification-feed__item-metaItem metadata row (category + time)
.cometchat-notification-feed__card-containerCard wrapper
.cometchat-notification-feed__loadingLoading state
.cometchat-notification-feed__emptyEmpty state
.cometchat-notification-feed__errorError state

Props

All props are optional.

title

Header title text.
Typestring
Default"Notifications"

showHeader

Shows/hides the entire header.
Typeboolean
Defaulttrue

showBackButton

Shows/hides the back button in the header.
Typeboolean
Defaultfalse

showFilterChips

Shows/hides the category filter chips row.
Typeboolean
Defaulttrue

notificationFeedRequestBuilder

Custom request builder for fetching feed items.
TypeCometChat.NotificationFeedRequestBuilder
DefaultSDK default (20 per page)

notificationCategoriesRequestBuilder

Custom request builder for fetching categories.
TypeCometChat.NotificationCategoriesRequestBuilder
DefaultSDK default (50 per page)

onItemClick

Callback fired when a feed item card is clicked.
Type(feedItem: NotificationFeedItem) => void
Defaultundefined

onActionClick

Callback fired when an interactive element inside a card is clicked.
Type(feedItem: NotificationFeedItem, action: CardAction) => void
Defaultundefined
The CardAction object contains:
  • type — Action type (e.g., "openUrl", "chatWithUser")
  • params — Action parameters (e.g., { url: "..." }, { uid: "..." })
  • elementId — ID of the element that triggered the action

onError

Callback fired when the component encounters an error.
Type(error: CometChat.CometChatException) => void
Defaultundefined

onBackPress

Callback fired when the back button is pressed.
Type() => void
Defaultundefined

cardThemeMode

Theme mode for the card renderer (@cometchat/cards-react).
Type"auto" | "light" | "dark"
Default"auto"

cardThemeOverride

Custom theme override passed to the card renderer.
TypeRecord<string, unknown>
Defaultundefined

headerView

Custom component replacing the entire header.
TypeReactNode
DefaultBuilt-in header with title and mark-all-read button

loadingView

Custom component displayed during the initial loading state.
TypeReactNode
DefaultBuilt-in loading state

errorView

Custom component displayed when an error occurs.
TypeReactNode
DefaultBuilt-in error state with retry button

emptyView

Custom component displayed when there are no notifications.
TypeReactNode
DefaultBuilt-in empty state with illustration

itemView

Custom renderer for each feed item.
Type(item: NotificationFeedItem) => ReactNode
DefaultBuilt-in card renderer

Additional Exports

useNotificationUnreadCount

A React hook for tracking unread notification count. Uses a shared singleton — multiple components share one polling interval and WebSocket listener.

Options

OptionTypeDefaultDescription
categorystringundefinedFilter count by category
pollingIntervalnumber30000Polling interval in milliseconds

Return Value

FieldTypeDescription
countnumberCurrent unread count
refresh() => Promise<void>Manually refresh the count
isLoadingbooleanWhether the initial fetch is in progress

Common Patterns

Show only unread items

Hide filter chips and header

Embed in a sidebar

Add notification badge to navigation


Next Steps

Campaigns Feature

Overview of how campaigns work end-to-end

SDK Campaigns API

Low-level SDK APIs for feed items, categories, and engagement

Theming

Customize colors, fonts, and appearance

Components

Browse all prebuilt UI components