> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/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">
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</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.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/XVuiTf1_iMM9sy8y/images/campaigns-overview-web.png?fit=max&auto=format&n=XVuiTf1_iMM9sy8y&q=85&s=85ec5cddd0e9685d947027b003a3d9f7" width="2880" height="1600" data-path="images/campaigns-overview-web.png" />
</Frame>

***

## 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 lines theme={null}
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

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

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

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

#### onBackPress

Fires when the back button in the header is clicked.

```tsx lines 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                            |
| Offline banner       | Shows connectivity warning when offline                                    |

***

## Custom View Slots

### headerView

Replace the entire header:

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

### State Views

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

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

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

```tsx lines 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>
  );
}
```

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

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

### Hide filter chips and header

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

### Deep link to a specific notification

```tsx lines theme={null}
<CometChatNotificationFeed
  scrollToItemId="notification-item-id-123"
/>
```

### Embed in a sidebar

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

### Add notification badge to navigation

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

<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/theme">
    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>