> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-agent-native-development.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` |
  | Import | `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';` |
  | Purpose | Full-screen notification feed component with category filtering, card rendering, real-time updates, and engagement reporting. |
  | Data props | `notificationFeedRequestBuilder` · `notificationCategoriesRequestBuilder` |
  | Actions | `onItemClick` · `onActionClick` · `onError` · `onBackPress` — [details](#actions-and-events) |
  | Styling | `style` — the app `ThemeData` does not reach inside a kit widget, so scope colours here. |
  | Layout | Fills its parent — place it in an `Expanded` (or a sized box) inside a `Column`, or layout throws an unbounded-height error at render. |
  | Prerequisites | `CometChatUIKit` initialised and a user logged in. |
  | Full props | [18 props](#properties) |
</Accordion>

`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, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b-docs-agent-native-development/SkICtQbidhdDKkU0/images/campaigns-overview.png?fit=max&auto=format&n=SkICtQbidhdDKkU0&q=85&s=7064084509f195af8eb12526915f6a36" width="2880" height="1666" data-path="images/campaigns-overview.png" />
</Frame>

***

## Where It Fits

`CometChatNotificationFeed` is a full-screen component. Drop it into a route or screen. It manages its own data fetching, state, and real-time listeners — you just handle navigation callbacks.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    class NotificationsScreen extends StatelessWidget {
      const NotificationsScreen({super.key});

      @override
      Widget build(BuildContext context) {
        return CometChatNotificationFeed(
          showBackButton: true,
          onBackPress: () => Navigator.of(context).pop(),
          onItemClick: (NotificationFeedItem item) {
            // Handle item tap (e.g., open detail or deep link)
          },
        );
      }
    }
    ```
  </Tab>
</Tabs>

***

## Quick Start

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

    @override
    Widget build(BuildContext context) {
      return const CometChatNotificationFeed();
    }
    ```
  </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="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      notificationFeedRequestBuilder: NotificationFeedRequestBuilder()
        ..setLimit(30)
        ..setReadState(FeedReadState.unread)
        ..setCategory("promotions"),
    )
    ```
  </Tab>
</Tabs>

### Filter Options

| Builder Method | Description |
| - | - |
| `.setLimit(int)` | Items per page (default 20, max 100) |
| `.setReadState(FeedReadState)` | `read`, `unread`, or `all` |
| `.setCategory(String)` | Filter by category ID |
| `.setChannelId(String)` | Filter by channel |
| `.setTags(List<String>)` | Filter by tags |
| `.setDateFrom(String)` | ISO 8601 date lower bound |
| `.setDateTo(String)` | ISO 8601 date upper bound |

<Warning>
  Pass the builder object (without calling `.build()`). The component calls `.build()` internally.
</Warning>

***

## Actions and Events

### Callback Methods

#### `onItemClick`

Fires when a feed item card is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      onItemClick: (NotificationFeedItem item) {
        // item.id, item.content (Card JSON), item.category
      },
    )
    ```
  </Tab>
</Tabs>

#### `onActionClick`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      onActionClick: (NotificationFeedItem item, CometChatCardActionEvent action) {
        if (action.action is CometChatCardOpenUrlAction) {
          // Open URL in browser
        } else if (action.action is CometChatCardChatWithUserAction) {
          // Navigate to chat
        }
      },
    )
    ```
  </Tab>
</Tabs>

#### `onError`

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

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      onError: (String error) {
        debugPrint("Feed error: $error");
      },
    )
    ```
  </Tab>
</Tabs>

#### `onBackPress`

Fires when the back button in the header is tapped.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      showBackButton: true,
      onBackPress: () => Navigator.of(context).pop(),
    )
    ```
  </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 |
| 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 |

***

## Properties

| Property | Type | Default | Description |
| - | - | - | - |
| `title` | `String` | `'Notifications'` | Header title text |
| `showHeader` | `bool` | `true` | Toggle header visibility |
| `showBackButton` | `bool` | `false` | Toggle back button |
| `showFilterChips` | `bool` | `true` | Toggle category filter chips |
| `headerView` | `Widget?` | `null` | Custom header widget |
| `scrollToItemId` | `String?` | `null` | Deep link to a specific item |
| `notificationFeedRequestBuilder` | `NotificationFeedRequestBuilder?` | `null` | Custom feed request |
| `notificationCategoriesRequestBuilder` | `NotificationCategoriesRequestBuilder?` | `null` | Custom categories request |
| `onItemClick` | `void Function(NotificationFeedItem feedItem)?` | `null` | Callback when a feed item card is tapped. |
| `onActionClick` | `void Function( NotificationFeedItem feedItem, CometChatCardActionEvent action, )?` | `null` | Callback when an action button within a card is tapped. |
| `onError` | `void Function(String error)?` | `null` | Callback when an error occurs. |
| `onBackPress` | `VoidCallback?` | `null` | Callback when back button is pressed. |
| `emptyStateView` | `Widget?` | `null` | Custom empty state view. |
| `errorStateView` | `Widget?` | `null` | Custom error state view. |
| `loadingStateView` | `Widget?` | `null` | Custom loading state view. |
| `style` | `CometChatNotificationFeedStyle?` | `null` | Style configuration for the notification feed. |
| `cardThemeMode` | `CometChatCardThemeMode?` | `null` | Card renderer theme mode |
| `cardThemeOverride` | `CometChatCardThemeOverride?` | `null` | Card renderer theme override |

***

## Custom View Slots

### Header View

Replace the entire header:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      headerView: Padding(
        padding: const EdgeInsets.all(16),
        child: Row(
          children: [
            Text(
              "My Notifications",
              style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
            ),
          ],
        ),
      ),
    )
    ```
  </Tab>
</Tabs>

### State Views

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      emptyStateView: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Icon(Icons.notifications_off, size: 64, color: Colors.grey),
            SizedBox(height: 16),
            Text("No notifications yet"),
          ],
        ),
      ),
      errorStateView: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text("Something went wrong"),
            ElevatedButton(
              onPressed: () { /* retry logic */ },
              child: Text("Retry"),
            ),
          ],
        ),
      ),
      loadingStateView: const Center(
        child: CircularProgressIndicator(),
      ),
    )
    ```
  </Tab>
</Tabs>

***

## Style

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      style: CometChatNotificationFeedStyle(
        backgroundColor: Color(0xFFF5F5F5),
        headerTitleColor: Color(0xFF141414),
        chipActiveBackgroundColor: Color(0xFF3399FF),
        chipActiveTextColor: Colors.white,
        chipInactiveBackgroundColor: Colors.transparent,
        chipInactiveTextColor: Color(0xFF727272),
        chipBorderColor: Color(0xFFE0E0E0),
        cardBackgroundColor: Colors.white,
        cardBorderColor: Color(0xFFE0E0E0),
        cardBorderRadius: 12,
        unreadIndicatorColor: Color(0xFF3399FF),
      ),
    )
    ```
  </Tab>
</Tabs>

### Style Properties

| Property | Type | Description |
| - | - | - |
| `backgroundColor` | Color? | Screen background color |
| `headerTitleColor` | Color? | Header title text color |
| `headerTitleTextStyle` | TextStyle? | Header title text style |
| `backIconColor` | Color? | Back button icon color |
| `chipActiveBackgroundColor` | Color? | Selected filter chip background |
| `chipActiveTextColor` | Color? | Selected filter chip text |
| `chipInactiveBackgroundColor` | Color? | Unselected filter chip background |
| `chipInactiveTextColor` | Color? | Unselected filter chip text |
| `chipBorderColor` | Color? | Filter chip border |
| `chipTextStyle` | TextStyle? | Filter chip text style |
| `badgeBackgroundColor` | Color? | Badge background |
| `badgeTextColor` | Color? | Badge text |
| `badgeTextStyle` | TextStyle? | Badge text style |
| `timestampTextColor` | Color? | Item timestamp color |
| `timestampTextStyle` | TextStyle? | Item timestamp style |
| `timestampHeaderTextStyle` | TextStyle? | Section header timestamp style |
| `timestampHeaderTextColor` | Color? | Section header timestamp color |
| `cardBackgroundColor` | Color? | Card container background |
| `cardBorderColor` | Color? | Card container border |
| `cardBorderRadius` | double? | Card corner radius |
| `cardBorderWidth` | double? | Card border width |
| `unreadIndicatorColor` | Color? | Unread dot indicator color |
| `separatorColor` | Color? | Separator between cards |

All colors default to `null` to inherit from `CometChatTheme`. Override individual values without losing theme support.

***

## Deep Linking

Navigate directly to a specific feed item using `scrollToItemId`:

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      scrollToItemId: "announcement-id-from-push",
    )
    ```
  </Tab>
</Tabs>

If the item is already loaded, the feed scrolls to it. If not, it fetches the item by ID and inserts it at the top.

***

## Common Patterns

### Show only unread items

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      notificationFeedRequestBuilder: NotificationFeedRequestBuilder()
        ..setReadState(FeedReadState.unread),
    )
    ```
  </Tab>
</Tabs>

### Hide filter chips and header

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      showHeader: false,
      showFilterChips: false,
    )
    ```
  </Tab>
</Tabs>

### Custom categories request

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      notificationCategoriesRequestBuilder: NotificationCategoriesRequestBuilder()
        ..setLimit(10),
    )
    ```
  </Tab>
</Tabs>

### Card theme mode override

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatNotificationFeed(
      cardThemeMode: CometChatCardThemeMode.dark,
    )
    ```
  </Tab>
</Tabs>

***

## Next Steps

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

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

  <Card title="Component Styling" icon="paintbrush" href="/ui-kit/flutter/component-styling">
    Full styling reference for all components
  </Card>

  <Card title="BLoC & Data Customization" icon="database" href="/ui-kit/flutter/customization-bloc-data">
    Custom BLoCs, repositories, and data sources
  </Card>
</CardGroup>


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