> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-rn-guide-message-privately.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.

`CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a native card using the CometChat Cards library. It handles fetching, pagination, category filtering, real-time updates, and read/delivered/engagement reporting automatically. Present it in a `UINavigationController`, push it onto an existing navigation stack, or embed it in a tab bar.

Each notification gets its own section header with the category label on the left and a relative timestamp on the right:

| Condition                   | Display                          |
| --------------------------- | -------------------------------- |
| Today (\< 24 hours ago)     | Time only — 2:35 PM              |
| Yesterday (24–48 hours ago) | Yesterday                        |
| This week (2–7 days ago)    | Day name — Monday, Tuesday, etc. |
| Older (> 7 days)            | Full date — 25/05/2026           |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(onItemClick: { feedItem in
        // Handle item tap (e.g., open detail or deep link)
    })

    let navController = UINavigationController(rootViewController: notificationFeed)
    self.present(navController, animated: true)
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    let navController = UINavigationController(rootViewController: notificationFeed)
    self.present(navController, animated: true)
    ```
  </Tab>
</Tabs>

Prerequisites: CometChat SDK initialized with `CometChatUIKit.init()` and a user logged in.

***

## Filtering Feed Items

Control what loads using custom request builders:

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(notificationFeedRequestBuilder:
        NotificationFeedRequest.NotificationFeedRequestBuilder()
            .set(limit: 30)
            .set(readState: .unread)
            .set(category: "promotions")
    )
    ```
  </Tab>
</Tabs>

### Filter Options

| Builder Method                   | Description                          |
| -------------------------------- | ------------------------------------ |
| `.set(limit: Int)`               | Items per page (default 20).         |
| `.set(readState: FeedReadState)` | `.read`, `.unread`, or omit for all. |
| `.set(category: String)`         | Filter by category name.             |
| `.set(categoryId: String)`       | Filter by category ID.               |
| `.set(channelId: String)`        | Filter by channel.                   |
| `.set(tags: [String])`           | Filter by tags.                      |
| `.set(dateFrom: String)`         | ISO 8601 date lower bound.           |
| `.set(dateTo: String)`           | ISO 8601 date upper bound.           |

Pass the builder object, not the result of `.build()`. The component calls `.build()` internally.

***

## Actions and Events

### onItemClick

Fires when a feed item card is tapped.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onItemClick: { feedItem in
        // feedItem.id, feedItem.content (Card JSON), feedItem.category
        print("Item tapped: \(feedItem.id)")
    })
    ```
  </Tab>
</Tabs>

***

### onActionClick

Fires when an interactive element (button, link) inside a card is tapped.

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onActionClick: { feedItem, actionEvent in
        // Report engagement on every action
        CometChat.reportFeedEngagement(feedItem, interactionString: "button_clicked", onSuccess: {}, onError: { _ in })

        // Handle the action
        switch actionEvent.action {
        case .openUrl(let url, _):
            if let link = URL(string: url) {
                UIApplication.shared.open(link)
            }
        case .chatWithUser(let uid):
            // Navigate to 1-on-1 chat
            break
        case .chatWithGroup(let guid):
            // Navigate to group chat
            break
        case .customCallback(let callbackId, let payload):
            // Custom app logic
            break
        default:
            break
        }
    })
    ```
  </Tab>
</Tabs>

***

### onError

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

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onError: { error in
        print("Feed error: \(error.errorDescription)")
    })
    ```
  </Tab>
</Tabs>

***

## Automatic Behaviors

The component handles these automatically — no manual setup needed:

| Behavior             | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| Real-time updates    | New items appear at the top via WebSocket listener.           |
| Delivery reporting   | Items are reported as delivered when fetched.                 |
| Read reporting       | Items are reported as read after 1 second of visibility.      |
| Unread count polling | Polls unread count every 30 seconds to update badges.         |
| Infinite scroll      | Fetches next page when scrolling near the bottom.             |
| Pull-to-refresh      | Resets and fetches fresh data on pull.                        |
| Timestamp grouping   | Groups items as "Today", "Yesterday", day name, or date.      |
| Category filtering   | Filter chips row for category-based filtering.                |
| Connection recovery  | Automatically refreshes when the app returns from background. |

***

## Functionality

| Method                                       | Description                                       |
| -------------------------------------------- | ------------------------------------------------- |
| `set(title: String)`                         | Header title text. Default "Notifications".       |
| `set(showBackButton: Bool)`                  | Toggle back button visibility. Default `true`.    |
| `set(showFilterChips: Bool)`                 | Toggle category filter chips. Default `true`.     |
| `set(cardThemeMode: String)`                 | Card rendering theme: "auto", "light", or "dark". |
| `set(notificationFeedRequestBuilder:)`       | Custom feed request builder.                      |
| `set(notificationCategoriesRequestBuilder:)` | Custom categories request builder.                |

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(title: "Activity")
    notificationFeed.set(showBackButton: false)
    notificationFeed.set(showFilterChips: true)
    notificationFeed.set(cardThemeMode: "dark")
    ```
  </Tab>
</Tabs>

***

## Common Patterns

### Show only unread items

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(notificationFeedRequestBuilder:
        NotificationFeedRequest.NotificationFeedRequestBuilder()
            .set(readState: .unread)
    )
    ```
  </Tab>
</Tabs>

### Hide filter chips

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(showFilterChips: false)
    ```
  </Tab>
</Tabs>

### Custom categories request

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(notificationCategoriesRequestBuilder:
        NotificationCategoriesRequest.NotificationCategoriesRequestBuilder()
            .set(limit: 10)
    )
    ```
  </Tab>
</Tabs>

### Embed in a Tab Bar

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    let notificationFeed = CometChatNotificationFeed()
    notificationFeed.set(showBackButton: false)
    notificationFeed.tabBarItem = UITabBarItem(
        title: "Notifications",
        image: UIImage(systemName: "bell"),
        selectedImage: UIImage(systemName: "bell.fill")
    )

    // Add to tab bar controller
    let navController = UINavigationController(rootViewController: notificationFeed)
    tabBarController.viewControllers?.append(navController)
    ```
  </Tab>
</Tabs>

### Handle action + report engagement

<Tabs>
  <Tab title="Swift">
    ```swift theme={null}
    notificationFeed.set(onActionClick: { feedItem, actionEvent in
        // Always report engagement
        CometChat.reportFeedEngagement(feedItem, interactionString: actionEvent.elementId, onSuccess: {}, onError: { _ in })

        switch actionEvent.action {
        case .openUrl(let url, _):
            if let link = URL(string: url) {
                UIApplication.shared.open(link)
            }
        case .chatWithUser(let uid):
            // Open CometChat messages with user
            break
        default:
            break
        }
    })
    ```
  </Tab>
</Tabs>

***

## Next Steps

| Topic                                      | Description                                                    |
| ------------------------------------------ | -------------------------------------------------------------- |
| [Campaigns Feature](/ui-kit/ios/campaigns) | Overview of how campaigns work end-to-end.                     |
| [SDK Campaigns API](/sdk/ios/campaigns)    | Low-level SDK APIs for feed items, categories, and engagement. |