Notification Feed - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatNotificationFeed",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatNotificationFeed } from \"@cometchat/chat-uikit-react\";",
  "cssImport": "import \"@cometchat/chat-uikit-react/css-variables.css\";",
  "description": "Full-screen notification feed with category filtering, timestamp grouping, card rendering via @cometchat/cards-react, real-time updates, and automatic engagement reporting.",
  "cssRootClass": ".cometchat-notification-feed",
  "props": {
    "data": {
      "title": { "type": "string", "default": "\"Notifications\"" },
      "scrollToItemId": { "type": "string", "default": "undefined", "note": "Deep link to a specific feed item" },
      "notificationFeedRequestBuilder": { "type": "NotificationFeedRequestBuilder", "default": "SDK default (20 per page)" },
      "notificationCategoriesRequestBuilder": { "type": "NotificationCategoriesRequestBuilder", "default": "SDK default (50 per page)" }
    },
    "callbacks": {
      "onItemClick": "(feedItem: NotificationFeedItem) => void",
      "onActionClick": "(feedItem: NotificationFeedItem, action: CardAction) => void",
      "onError": "(error: CometChat.CometChatException) => void",
      "onBackPress": "() => void"
    },
    "visibility": {
      "showHeader": { "type": "boolean", "default": true },
      "showBackButton": { "type": "boolean", "default": false },
      "showFilterChips": { "type": "boolean", "default": true }
    },
    "viewSlots": {
      "headerView": "React.ReactNode",
      "emptyStateView": "React.ReactNode",
      "errorStateView": "React.ReactNode",
      "loadingStateView": "React.ReactNode"
    },
    "cards": {
      "cardThemeMode": { "type": "\"auto\" | \"light\" | \"dark\"", "default": "\"auto\"" },
      "cardThemeOverride": { "type": "Record<string, any>", "default": "undefined" }
    },
    "style": {
      "type": "CometChatNotificationFeedStyle",
      "properties": {
        "backgroundColor": "string",
        "width": "string",
        "height": "string",
        "headerTitleColor": "string",
        "headerTitleFont": "string",
        "chipActiveBackgroundColor": "string",
        "chipActiveTextColor": "string",
        "chipInactiveBackgroundColor": "string",
        "chipInactiveTextColor": "string",
        "chipBorderColor": "string",
        "badgeBackgroundColor": "string",
        "badgeTextColor": "string",
        "separatorColor": "string",
        "timestampTextColor": "string",
        "timestampFont": "string",
        "cardBackgroundColor": "string",
        "cardBorderColor": "string",
        "cardBorderRadius": "number",
        "cardBorderWidth": "number",
        "unreadIndicatorColor": "string"
      }
    }
  },
  "automaticBehaviors": [
    "Real-time updates via WebSocket listener",
    "Delivery reporting on fetch",
    "Read reporting on viewport visibility (IntersectionObserver)",
    "Unread count polling every 30 seconds",
    "Infinite scroll pagination",
    "Timestamp grouping (Today, Yesterday, day name, date)",
    "Category filter chips with unread badges",
    "Mark all read button",
    "Offline connectivity banner"
  ],
  "additionalExports": {
    "CometChatNotificationBadge": "Standalone unread count badge component",
    "useNotificationUnreadCount": "Hook for tracking unread count with shared polling"
  }
}

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.

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.

import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function NotificationsPage() {
  return (
    <CometChatNotificationFeed
      showBackButton={true}
      onBackPress={() => window.history.back()}
      onItemClick={(item) => {
        // Handle item click (e.g., open detail or deep link)
      }}
    />
  );
}

Minimal Render

import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function NotificationsDemo() {
  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <CometChatNotificationFeed />
    </div>
  );
}

export default NotificationsDemo;

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:

import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
import { CometChat } from "@cometchat/chat-sdk-javascript";

function UnreadNotifications() {
  return (
    <CometChatNotificationFeed
      notificationFeedRequestBuilder={
        new CometChat.NotificationFeedRequestBuilder()
          .setLimit(30)
          .setReadState("unread")
          .setCategory("promotions")
          .build()
      }
    />
  );
}

Builder Method	Description
`.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.

<CometChatNotificationFeed
  onItemClick={(item) => {
    console.log("Item clicked:", item.getId());
  }}
/>

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.

<CometChatNotificationFeed
  onActionClick={(item, action) => {
    const { type, params, elementId } = action;
    switch (type) {
      case "openUrl":
        window.open(params.url, "_blank");
        break;
      case "chatWithUser":
        // Navigate to chat with params.uid
        break;
      case "chatWithGroup":
        // Navigate to group chat with params.guid
        break;
    }
  }}
/>

onError

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

<CometChatNotificationFeed
  onError={(error) => {
    console.error("Feed error:", error.message);
  }}
/>

onBackPress

Fires when the back button in the header is clicked.

<CometChatNotificationFeed
  showBackButton={true}
  onBackPress={() => window.history.back()}
/>

Automatic Behaviors

The component handles these automatically — no manual setup needed:

Behavior	Description
Real-time updates	New items appear at the top via WebSocket `NotificationFeedListener`
Delivery reporting	Items are reported as delivered when fetched
Read reporting	Items are reported as read when visible in viewport (IntersectionObserver)
Unread count polling	Polls unread count every 30 seconds to update badges
Infinite scroll	Fetches next page when scrolling near the bottom
Timestamp grouping	Groups items as “Today”, “Yesterday”, day name, or date
Category filtering	Filter chips row with per-category unread badges
Mark all read	Header button to mark all notifications as read
Offline banner	Shows connectivity warning when offline

Custom View Slots

headerView

Replace the entire header:

<CometChatNotificationFeed
  headerView={
    <div style={{ padding: 16, display: "flex", alignItems: "center" }}>
      <h2 style={{ margin: 0, fontSize: 20, fontWeight: "bold" }}>My Notifications</h2>
    </div>
  }
/>

State Views

<CometChatNotificationFeed
  emptyStateView={
    <div style={{ display: "grid", placeItems: "center", height: "100%" }}>
      <p>No notifications yet</p>
    </div>
  }
  errorStateView={
    <div style={{ display: "grid", placeItems: "center", height: "100%" }}>
      <p>Something went wrong</p>
    </div>
  }
  loadingStateView={
    <div style={{ display: "grid", placeItems: "center", height: "100%" }}>
      <div className="spinner" />
    </div>
  }
/>

Styling

The component uses CSS variables from the CometChat theme system. Pass a style prop for programmatic overrides, or use CSS classes for full control.

Style Prop

import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

function StyledNotifications() {
  return (
    <CometChatNotificationFeed
      style={{
        backgroundColor: "#F5F5F5",
        chipActiveBackgroundColor: "#6852D6",
        chipActiveTextColor: "#FFFFFF",
        chipInactiveBackgroundColor: "#FFFFFF",
        chipInactiveTextColor: "#727272",
        chipBorderColor: "#E0E0E0",
        cardBackgroundColor: "#FFFFFF",
        cardBorderColor: "#E0E0E0",
        cardBorderRadius: 8,
        unreadIndicatorColor: "#6852D6",
      }}
    />
  );
}

Style Properties

Property	Type	Description
`backgroundColor`	string	Root container background
`width`	string	Container width
`height`	string	Container height
`headerTitleColor`	string	Header title text color
`headerTitleFont`	string	Header title font
`chipActiveBackgroundColor`	string	Selected filter chip background
`chipActiveTextColor`	string	Selected filter chip text color
`chipInactiveBackgroundColor`	string	Unselected filter chip background
`chipInactiveTextColor`	string	Unselected filter chip text color
`chipBorderColor`	string	Inactive chip border color
`badgeBackgroundColor`	string	Badge background color
`badgeTextColor`	string	Badge text color
`separatorColor`	string	Separator between items
`timestampTextColor`	string	Timestamp text color
`timestampFont`	string	Timestamp font
`cardBackgroundColor`	string	Card container background
`cardBorderColor`	string	Card border color
`cardBorderRadius`	number	Card corner radius
`cardBorderWidth`	number	Card border width
`unreadIndicatorColor`	string	Unread dot color

CSS Classes

Override styles using these CSS classes:

Class	Description
`.cometchat-notification-feed`	Root container
`.cometchat-notification-feed__header`	Header bar
`.cometchat-notification-feed__header-title`	Header title text
`.cometchat-notification-feed__header-back`	Back button
`.cometchat-notification-feed__mark-all-read`	Mark all read button
`.cometchat-notification-feed__chips`	Filter chips container
`.cometchat-notification-feed__chip`	Individual filter chip
`.cometchat-notification-feed__chip--active`	Active filter chip
`.cometchat-notification-feed__chip--inactive`	Inactive filter chip
`.cometchat-notification-feed__chip--inactive-with-badge`	Inactive chip with unread badge
`.cometchat-notification-feed__chip-badge`	Chip unread badge
`.cometchat-notification-feed__chip-badge--active`	Active chip badge
`.cometchat-notification-feed__chip-badge--inactive`	Inactive chip badge
`.cometchat-notification-feed__content`	Scrollable content area
`.cometchat-notification-feed__item`	Feed item container
`.cometchat-notification-feed__item--unread`	Unread feed item
`.cometchat-notification-feed__unread-indicator`	Unread dot indicator
`.cometchat-notification-feed__item-meta`	Item metadata row (category + time)
`.cometchat-notification-feed__item-category`	Category label
`.cometchat-notification-feed__item-time`	Timestamp
`.cometchat-notification-feed__card-container`	Card wrapper
`.cometchat-notification-feed__loading`	Loading state
`.cometchat-notification-feed__empty`	Empty state
`.cometchat-notification-feed__error`	Error state
`.cometchat-notification-feed__connectivity-banner`	Offline banner

Props

All props are optional.

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.


Type	`Record<string, any>`
Default	`undefined`

emptyStateView

Custom component displayed when there are no notifications.


Type	`React.ReactNode`
Default	Built-in empty state with illustration

errorStateView

Custom component displayed when an error occurs.


Type	`React.ReactNode`
Default	Built-in error state with retry button

headerView

Custom component replacing the entire header.


Type	`React.ReactNode`
Default	Built-in header with title and mark-all-read button

loadingStateView

Custom component displayed during the initial loading state.


Type	`React.ReactNode`
Default	Built-in loading spinner

notificationCategoriesRequestBuilder

Custom request builder for fetching categories.


Type	`CometChat.NotificationCategoriesRequestBuilder`
Default	SDK default (50 per page)

notificationFeedRequestBuilder

Custom request builder for fetching feed items.


Type	`CometChat.NotificationFeedRequestBuilder`
Default	SDK default (20 per page)

onActionClick

Callback fired when an interactive element inside a card is clicked.


Type	`(feedItem: NotificationFeedItem, action: CardAction) => void`
Default	`undefined`

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

onBackPress

Callback fired when the back button is pressed.


Type	`() => void`
Default	`undefined`

onError

Callback fired when the component encounters an error.


Type	`(error: CometChat.CometChatException) => void`
Default	`undefined`

onItemClick

Callback fired when a feed item card is clicked.


Type	`(feedItem: NotificationFeedItem) => void`
Default	`undefined`

scrollToItemId

Deep link to a specific feed item by ID. The component scrolls to the item once loaded.


Type	`string`
Default	`undefined`

showBackButton

Shows/hides the back button in the header.


Type	`boolean`
Default	`false`

showFilterChips

Shows/hides the category filter chips row.


Type	`boolean`
Default	`true`

showHeader

Shows/hides the entire header.


Type	`boolean`
Default	`true`

style

Style customization object.


Type	`CometChatNotificationFeedStyle`
Default	`undefined`

title

Header title text.


Type	`string`
Default	`"Notifications"`

Additional Exports

CometChatNotificationBadge

A standalone badge component that displays the unread notification count. Uses a shared polling singleton — multiple badges share one interval and listener.

import { CometChatNotificationBadge } from "@cometchat/chat-uikit-react";

function NavBar() {
  return (
    <nav>
      <a href="/notifications">
        Notifications <CometChatNotificationBadge />
      </a>
    </nav>
  );
}

Props

Prop	Type	Default	Description
`category`	string	undefined	Filter count by category
`max`	number	99	Maximum count before showing “N+“
`style.backgroundColor`	string	`"#6852D6"`	Badge background color
`style.textColor`	string	`"#fff"`	Badge text color
`style.fontSize`	string	`"11px"`	Badge font size
`style.borderRadius`	string	`"9999px"`	Badge border radius

useNotificationUnreadCount

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

import { useNotificationUnreadCount } from "@cometchat/chat-uikit-react";

function NotificationIcon() {
  const { count, refresh, isLoading } = useNotificationUnreadCount();

  return (
    <button onClick={refresh}>
      🔔 {count > 0 && <span className="badge">{count}</span>}
    </button>
  );
}

Return Value

Field	Type	Description
`count`	number	Current unread count
`refresh`	`() => Promise<void>`	Manually refresh the count
`isLoading`	boolean	Whether the initial fetch is in progress

Options

Option	Type	Default	Description
`category`	string	undefined	Filter count by category
`pollingInterval`	number	30000	Polling interval in milliseconds

Common Patterns

Show only unread items

<CometChatNotificationFeed
  notificationFeedRequestBuilder={
    new CometChat.NotificationFeedRequestBuilder()
      .setReadState("unread")
      .build()
  }
/>

Hide filter chips and header

<CometChatNotificationFeed
  showHeader={false}
  showFilterChips={false}
/>

Deep link to a specific notification

<CometChatNotificationFeed
  scrollToItemId="notification-item-id-123"
/>

import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function NotificationsSidebar() {
  return (
    <div style={{ width: 400, height: "100vh", borderLeft: "1px solid #E0E0E0" }}>
      <CometChatNotificationFeed
        title="Updates"
        showBackButton={false}
      />
    </div>
  );
}

import {
  CometChatNotificationFeed,
  CometChatNotificationBadge,
} from "@cometchat/chat-uikit-react";
import "@cometchat/chat-uikit-react/css-variables.css";

function App() {
  const [showFeed, setShowFeed] = useState(false);

  return (
    <>
      <nav>
        <button onClick={() => setShowFeed(!showFeed)}>
          🔔 <CometChatNotificationBadge max={99} />
        </button>
      </nav>
      {showFeed && (
        <CometChatNotificationFeed
          onBackPress={() => setShowFeed(false)}
          showBackButton={true}
        />
      )}
    </>
  );
}

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

​Where It Fits

​Minimal Render

​Filtering Feed Items

​Filter Options

​Actions and Events

​Callback Props

​onItemClick

​onActionClick

​onError

​onBackPress

​Automatic Behaviors

​Custom View Slots

​headerView

​State Views

​Styling

​Style Prop

​Style Properties

​CSS Classes

​Props

​cardThemeMode

​cardThemeOverride

​emptyStateView

​errorStateView

​headerView

​loadingStateView

​notificationCategoriesRequestBuilder

​notificationFeedRequestBuilder

​onActionClick

​onBackPress

​onError

​onItemClick

​scrollToItemId

​showBackButton

​showFilterChips

​showHeader

​style

​title

​Additional Exports

​CometChatNotificationBadge

​Props

​useNotificationUnreadCount

​Return Value

​Options

​Common Patterns

​Show only unread items

​Hide filter chips and header

​Deep link to a specific notification

​Embed in a sidebar

​Add notification badge to navigation

​Next Steps

Campaigns Feature

SDK Campaigns API

Theming

Components

Where It Fits

Minimal Render

Filtering Feed Items

Filter Options

Actions and Events

Callback Props

onItemClick

onActionClick

onError

onBackPress

Automatic Behaviors

Custom View Slots

headerView

State Views

Styling

Style Prop

Style Properties

CSS Classes

Props

cardThemeMode

cardThemeOverride

emptyStateView

errorStateView

headerView

loadingStateView

notificationCategoriesRequestBuilder

notificationFeedRequestBuilder

onActionClick

onBackPress

onError

onItemClick

scrollToItemId

showBackButton

showFilterChips

showHeader

style

title

Additional Exports

CometChatNotificationBadge

Props

useNotificationUnreadCount

Return Value

Options

Common Patterns

Show only unread items

Hide filter chips and header

Deep link to a specific notification

Embed in a sidebar

Add notification badge to navigation

Next Steps