> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.