Notification Feed - CometChat Docs

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.

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.

Dart

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)
      },
    );
  }
}

Quick Start

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';

@override
Widget build(BuildContext context) {
  return const CometChatNotificationFeed();
}

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

Filtering Feed Items

Control what loads using custom request builders:

Dart

CometChatNotificationFeed(
  notificationFeedRequestBuilder: NotificationFeedRequestBuilder()
    ..setLimit(30)
    ..setReadState(FeedReadState.unread)
    ..setCategory("promotions"),
)

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

Pass the builder object (without calling .build()). The component calls .build() internally.

Actions and Events

Callback Methods

`onItemClick`

Fires when a feed item card is tapped.

Dart

CometChatNotificationFeed(
  onItemClick: (NotificationFeedItem item) {
    // item.id, item.content (Card JSON), item.category
  },
)

`onActionClick`

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

Dart

CometChatNotificationFeed(
  onActionClick: (NotificationFeedItem item, CometChatCardActionEvent action) {
    if (action.action is CometChatCardOpenUrlAction) {
      // Open URL in browser
    } else if (action.action is CometChatCardChatWithUserAction) {
      // Navigate to chat
    }
  },
)

`onError`

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

Dart

CometChatNotificationFeed(
  onError: (String error) {
    debugPrint("Feed error: $error");
  },
)

`onBackPress`

Fires when the back button in the header is tapped.

Dart

CometChatNotificationFeed(
  showBackButton: true,
  onBackPress: () => Navigator.of(context).pop(),
)

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
`cardThemeMode`	CometChatCardThemeMode?	null	Card renderer theme mode
`cardThemeOverride`	CometChatCardThemeOverride?	null	Card renderer theme override

Custom View Slots

Header View

Replace the entire header:

Dart

CometChatNotificationFeed(
  headerView: Padding(
    padding: const EdgeInsets.all(16),
    child: Row(
      children: [
        Text(
          "My Notifications",
          style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
        ),
      ],
    ),
  ),
)

State Views

Dart

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(),
  ),
)

Style

Dart

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),
  ),
)

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:

Dart

CometChatNotificationFeed(
  scrollToItemId: "announcement-id-from-push",
)

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

Dart

CometChatNotificationFeed(
  notificationFeedRequestBuilder: NotificationFeedRequestBuilder()
    ..setReadState(FeedReadState.unread),
)

Hide filter chips and header

Dart

CometChatNotificationFeed(
  showHeader: false,
  showFilterChips: false,
)

Custom categories request

Dart

CometChatNotificationFeed(
  notificationCategoriesRequestBuilder: NotificationCategoriesRequestBuilder()
    ..setLimit(10),
)

Card theme mode override

Dart

CometChatNotificationFeed(
  cardThemeMode: CometChatCardThemeMode.dark,
)

Next Steps

Campaigns Feature

Overview of how campaigns work end-to-end

SDK Campaigns API

Low-level SDK APIs for feed items, categories, and engagement

Component Styling

Full styling reference for all components

BLoC & Data Customization

Custom BLoCs, repositories, and data sources

​Where It Fits

​Quick Start

​Filtering Feed Items

​Filter Options

​Actions and Events

​Callback Methods

​onItemClick

​onActionClick

​onError

​onBackPress

​Automatic Behaviors

​Properties

​Custom View Slots

​Header View

​State Views

​Style

​Style Properties

​Deep Linking

​Common Patterns

​Show only unread items

​Hide filter chips and header

​Custom categories request

​Card theme mode override

​Next Steps

Campaigns Feature

SDK Campaigns API

Component Styling

BLoC & Data Customization

Where It Fits

Quick Start

Filtering Feed Items

Filter Options

Actions and Events

Callback Methods

`onItemClick`

`onActionClick`

`onError`

`onBackPress`

Automatic Behaviors

Properties

Custom View Slots

Header View

State Views

Style

Style Properties

Deep Linking

Common Patterns

Show only unread items

Hide filter chips and header

Custom categories request

Card theme mode override

Next Steps