> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-react-v7-feature-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification Feed

> Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting.

<Accordion title="AI Integration Quick Reference">
  | Field                     | Value                                                                                                                                                                                   |
  | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Component                 | `CometChatNotificationFeed`                                                                                                                                                             |
  | Package                   | `@cometchat/chat-uikit-react`                                                                                                                                                           |
  | Import                    | `import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";`                                                                                                              |
  | CSS root class            | `.cometchat-notification-feed`                                                                                                                                                          |
  | Primary output            | `onItemClick: (feedItem: NotificationFeedItem) => void` — emits the clicked feed item                                                                                                   |
  | Prerequisites             | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus [Campaigns](/ui-kit/react/campaigns) configured in the Dashboard |
  | Stitching                 | Wire `onItemClick` / `onActionClick` to route the tapped notification (see [Campaigns](/ui-kit/react/campaigns))                                                                        |
  | SDK listeners (automatic) | Real-time feed updates, delivery/read reporting, and unread-count polling — handled internally                                                                                          |
  | Full props                | See [Props](#props)                                                                                                                                                                     |
</Accordion>

`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.

<Note>
  **Prerequisite: Campaigns must be configured first.** The feed only shows content once **Campaigns / Notifications are set up in the CometChat Dashboard** — channels, categories, and card templates. Without this, the feed renders but stays empty. See [Campaigns](/ui-kit/react/campaigns) for the end-to-end setup (Dashboard configuration through frontend wiring).
</Note>

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-react-v7-feature-guides/nW_BSPBDUXv6ah2Z/images/campaigns-overview-web.png?fit=max&auto=format&n=nW_BSPBDUXv6ah2Z&q=85&s=37f33e7b3528ea294687d9955c46761c" width="2880" height="1600" data-path="images/campaigns-overview-web.png" />
</Frame>

<Info>
  **Live Preview** — interact with the notification feed component.

  [Open in Storybook ↗](https://storybook.cometchat.io/react/?path=/story/components-notification-feed-cometchat-notification-feed--default)
</Info>

<iframe src="https://storybook.cometchat.io/react/iframe.html?id=components-notification-feed-cometchat-notification-feed--default&viewMode=story&shortcuts=false&singleStory=true" className="w-full rounded-xl" loading="lazy" style={{height: "800px", border: "1px solid #e0e0e0"}} title="CometChat Notification Feed — Default" allow="clipboard-write" />

***

## 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.

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

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

***

## Minimal Render

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

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:

```tsx theme={null}
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()
      }
    />
  );
}
```

### Filter Options

| 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.

```tsx theme={null}
<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.

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

<Note>
  **Navigation is your app's responsibility.** `onItemClick` and `onActionClick` only report the intent (deep link, `chatWithUser`, `chatWithGroup`, `openUrl`) — the component does not route anywhere on its own. Your app must handle the transition (open the URL, switch to the chat with `params.uid` / `params.guid`, etc.). For the recommended navigation-event pattern, see [Event System — Navigation](/ui-kit/react/event-system#navigation).
</Note>

#### onError

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

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

#### onBackPress

Fires when the back button in the header is clicked.

```tsx theme={null}
<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                            |

***

## Customization

### View Props

```tsx theme={null}
<CometChatNotificationFeed
  headerView={<MyCustomHeader />}
  emptyView={<EmptyState />}
  loadingView={<Skeleton />}
  errorView={<ErrorBanner />}
  itemView={(item) => <MyCustomCard item={item} />}
/>
```

| Slot          | Signature                                   | Replaces                       |
| ------------- | ------------------------------------------- | ------------------------------ |
| `headerView`  | `ReactNode`                                 | Entire header bar              |
| `loadingView` | `ReactNode`                                 | Loading state                  |
| `emptyView`   | `ReactNode`                                 | Empty state                    |
| `errorView`   | `ReactNode`                                 | Error state                    |
| `itemView`    | `(item: NotificationFeedItem) => ReactNode` | Individual feed item rendering |

### Compound Composition

For full layout control, use sub-components. Omit any sub-component to hide it:

```tsx theme={null}
<CometChatNotificationFeed.Root onItemClick={handleClick}>
  <CometChatNotificationFeed.Header />
  <CometChatNotificationFeed.FilterChips />
  <CometChatNotificationFeed.List />
</CometChatNotificationFeed.Root>
```

Available sub-components:

| Sub-component  | Description                           | Props                                                | Flat API equivalent |
| -------------- | ------------------------------------- | ---------------------------------------------------- | ------------------- |
| `Root`         | Context provider and container        | All Root props + `children`                          | —                   |
| `Header`       | Header bar with title + mark-all-read | `title`, `showBackButton`, `onBackPress`, `children` | `headerView`        |
| `FilterChips`  | Category filter chips                 | `children`                                           | —                   |
| `List`         | Scrollable feed list                  | `itemView`                                           | `itemView`          |
| `Item`         | Individual feed item                  | `item`, `cardThemeMode`, `cardThemeOverride`         | —                   |
| `EmptyState`   | Empty state                           | `children`                                           | `emptyView`         |
| `ErrorState`   | Error state                           | `children`                                           | `errorView`         |
| `LoadingState` | Loading state                         | `children`                                           | `loadingView`       |

### CSS Styling

Override design tokens on the component selector:

```css theme={null}
.cometchat-notification-feed {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}
```

### 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-badge`       | Chip unread 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__card-container`   | Card wrapper                        |
| `.cometchat-notification-feed__loading`          | Loading state                       |
| `.cometchat-notification-feed__empty`            | Empty state                         |
| `.cometchat-notification-feed__error`            | Error state                         |

***

## Props

All props are optional.

***

### title

Header title text.

|         |                   |
| ------- | ----------------- |
| Type    | `string`          |
| Default | `"Notifications"` |

***

### showHeader

Shows/hides the entire header.

|         |           |
| ------- | --------- |
| Type    | `boolean` |
| Default | `true`    |

***

### 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`    |

***

### notificationFeedRequestBuilder

Custom request builder for fetching feed items.

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

***

### notificationCategoriesRequestBuilder

Custom request builder for fetching categories.

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

***

### onItemClick

Callback fired when a feed item card is clicked.

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

***

### 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

***

### onError

Callback fired when the component encounters an error.

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

***

### onBackPress

Callback fired when the back button is pressed.

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

***

### 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, unknown>` |
| Default | `undefined`               |

***

### headerView

Custom component replacing the entire header.

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

***

### loadingView

Custom component displayed during the initial loading state.

|         |                        |
| ------- | ---------------------- |
| Type    | `ReactNode`            |
| Default | Built-in loading state |

***

### errorView

Custom component displayed when an error occurs.

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

***

### emptyView

Custom component displayed when there are no notifications.

|         |                                        |
| ------- | -------------------------------------- |
| Type    | `ReactNode`                            |
| Default | Built-in empty state with illustration |

***

### itemView

Custom renderer for each feed item.

|         |                                             |
| ------- | ------------------------------------------- |
| Type    | `(item: NotificationFeedItem) => ReactNode` |
| Default | Built-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.

```tsx theme={null}
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>
  );
}
```

#### Options

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

#### 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 |

***

## Common Patterns

### Show only unread items

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

### Hide filter chips and header

```tsx theme={null}
<CometChatNotificationFeed
  showHeader={false}
  showFilterChips={false}
/>
```

### Embed in a sidebar

```tsx theme={null}
import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";

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

### Add notification badge to navigation

```tsx theme={null}
import { useState } from "react";
import {
  CometChatNotificationFeed,
  useNotificationUnreadCount,
} from "@cometchat/chat-uikit-react";

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

  return (
    <>
      <nav>
        <button onClick={() => setShowFeed(!showFeed)}>
          🔔 {count > 0 && <span className="badge">{count}</span>}
        </button>
      </nav>
      {showFeed && (
        <CometChatNotificationFeed
          onBackPress={() => setShowFeed(false)}
          showBackButton={true}
        />
      )}
    </>
  );
}
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Campaigns Feature" icon="bullhorn" href="/ui-kit/react/campaigns">
    Overview of how campaigns work end-to-end
  </Card>

  <Card title="SDK Campaigns API" icon="code" href="/sdk/javascript/campaigns">
    Low-level SDK APIs for feed items, categories, and engagement
  </Card>

  <Card title="Theming" icon="paintbrush" href="/ui-kit/react/theming">
    Customize colors, fonts, and appearance
  </Card>

  <Card title="Components" icon="grid-2" href="/ui-kit/react/components-overview">
    Browse all prebuilt UI components
  </Card>
</CardGroup>