Threaded Messages Header - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatThreadedHeader`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	Header component for threaded conversations showing the parent message, reply count, and thread navigation.
Data props	`parentMessage` · `loggedInUser`
Actions	`onThreadSubscriptionChange` — details
View slots	`messageActionView` — details
Styling	`style` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Prerequisites	`CometChatUIKit` initialised and a user logged in.
Full props	14 props

CometChatThreadedHeader displays the parent message of a thread along with reply count and provides the container for threaded message list and composer. It enables organized threaded conversations within a chat.

Where It Fits

CometChatThreadedHeader is used when a user taps “Reply in Thread” on a message. It wraps the parent message display with a CometChatMessageList (filtered by parentMessageId) and CometChatMessageComposer for thread replies.

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
)

Quick Start

Dart

import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
import 'package:flutter/material.dart';

class ThreadScreen extends StatelessWidget {
  final BaseMessage parentMessage;
  final User loggedInUser;

  const ThreadScreen({
    super.key,
    required this.parentMessage,
    required this.loggedInUser,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: CometChatThreadedHeader(
          parentMessage: parentMessage,
          loggedInUser: loggedInUser,
        ),
      ),
    );
  }
}

Typically launched from the message list when a user selects “Reply in Thread”:

Dart

CometChatMessageList(
  user: user,
  onThreadRepliesClick: (message, context, {template}) {
    Navigator.push(context, MaterialPageRoute(
      builder: (context) => ThreadScreen(
        parentMessage: message,
        loggedInUser: CometChatUIKit.loggedInUser!,
      ),
    ));
  },
)

Prerequisites: CometChat SDK initialized, a user logged in, and a valid BaseMessage object as the parent message.

Actions and Events

CometChatThreadedHeader renders the parent-message context only — it exposes no onBack or onError callback. Provide navigation from the screen that hosts it: a pushed route already gets a back button from its AppBar, so no wiring is required.

Dart

Scaffold(
  appBar: AppBar(title: const Text("Thread")),   // back button is automatic on a pushed route
  body: SafeArea(
    child: Column(
      children: [
        CometChatThreadedHeader(
          parentMessage: parentMessage,
          loggedInUser: loggedInUser,
        ),
        Expanded(
          child: CometChatMessageList(
            user: user,
            group: group,
            parentMessageId: parentMessage.id,
          ),
        ),
        CometChatMessageComposer(
          user: user,
          group: group,
          parentMessageId: parentMessage.id,
        ),
      ],
    ),
  ),
)

The thread list and composer each need parentMessageId and the same user/group target as the parent chat. Passing parentMessageId alone sends replies to the wrong target.

Custom message actions

Use messageActionView to render your own actions next to the parent message.

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
  messageActionView: (BaseMessage message, BuildContext context) {
    return IconButton(
      icon: const Icon(Icons.more_vert),
      onPressed: () {},
    );
  },
)

Thread subscription

Available since v6.1.1 With UIKitSettings.enableThreadSubscription on, the reply-count row carries a subscribe / unsubscribe control for the thread. It flips on tap, reverts with a toast if the server rejects the change, and ignores taps while a request is in flight. onThreadSubscriptionChange fires after a toggle from this control succeeds, with the parent message ID and the new state:

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
  onThreadSubscriptionChange: (int parentMessageId, bool subscribed) {
    if (!subscribed) _removeThreadRow(parentMessageId);
  },
)

To follow changes made from any surface — this control, the message action menu, or the bell on Message Header — listen for ccThreadSubscriptionChanged on CometChatMessageEvents instead. Set threadSubscriptionVisibility: false to hide the control, for example when the header above it already carries the bell. Setting messageActionView also replaces it.

SDK Events (Real-Time, Automatic)

SDK Listener	Internal behavior
New thread reply received	Increments reply count
Parent message edited	Updates parent message display
Parent message deleted	Updates parent message display

Functionality

Property	Type	Default	Description
`parentMessage`	`BaseMessage`	required	The parent message of the thread
`messageActionView`	`Function(BaseMessage message, BuildContext context)?`	`null`	`messageActionView` custom action view
`style`	`CometChatThreadedHeaderStyle?`	`null`	`style` style parameter
`loggedInUser`	`User`	required	The currently logged-in user
`template`	`CometChatMessageTemplate?`	`null`	`template` to get the message template
`height`	`double?`	`null`	`height` provides height to the widget
`width`	`double?`	`null`	`width` provides width to the widget
`receiptsVisibility`	`bool?`	`true`	`receiptsVisibility` controls visibility of receipts
`threadSubscriptionVisibility`	`bool?`	`true`	Shows the subscribe/unsubscribe bell in the reply-count row. Renders only when `UIKitSettings.enableThreadSubscription` is `true`, and is bypassed when `messageActionView` is set. Available since v6.1.1.
`onThreadSubscriptionChange`	`Function(int parentMessageId, bool subscribed)?`	`null`	Called after a subscribe/unsubscribe toggle succeeds, with the parent message ID and the new state. Available since v6.1.1.
`textFormatters`	`List<CometChatTextFormatter>?`	`null`	`textFormatters` list of text formatters.
`typography`	`CometChatTypography?`	`null`	`typography` optional pre-cached typography for optimization
`spacing`	`CometChatSpacing?`	`null`	`spacing` optional pre-cached spacing for optimization
`threadedHeaderBloc`	`ThreadedHeaderBloc?`	`null`	Your own bloc, used instead of the one the header creates. The header neither initializes nor closes it. See BLoC Access. Available since v6.2.0.

Custom View Slots

Bubble View

Replace the parent message bubble display. CometChatThreadedHeader has no bubbleView parameter of its own — pass a CometChatMessageTemplate via template and override its bubbleView.

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
  template: CometChatMessageTemplate(
    type: CometChatMessageType.text,
    category: CometChatMessageCategory.message,
    bubbleView: (message, context, alignment) {
      if (message is TextMessage) {
        return Container(
          padding: const EdgeInsets.all(12),
          decoration: BoxDecoration(
            color: const Color(0xFFF5F5F5),
            borderRadius: BorderRadius.circular(8),
          ),
          child: Text(message.text),
        );
      }
      return const SizedBox.shrink();
    },
  ),
)

Advanced

BLoC Access

The threaded header uses ThreadedHeaderBloc internally:

Component	Description
`ThreadedHeaderBloc`	Manages threaded header state
`ThreadedHeaderEvent`	Events: `InitializeThreadedHeader`, `IncrementReplyCount`, `UpdateParentMessage`, `UpdateThreadSubscription` (v6.1.1 and later)
`ThreadedHeaderState`	Threaded header state with parent message and reply count

Available since v6.2.0. Pass your own instance through threadedHeaderBloc to own that state. The header then leaves the bloc’s lifecycle to you: it does not dispatch InitializeThreadedHeader and does not close the bloc, so do both yourself — an uninitialized bloc renders an empty header.

Dart

class _ThreadScreenState extends State<ThreadScreen> {
  late final ThreadedHeaderBloc _headerBloc = ThreadedHeaderBloc()
    ..add(InitializeThreadedHeader(
      parentMessage: widget.parentMessage,
      loggedInUser: widget.loggedInUser,
    ));

  @override
  void dispose() {
    _headerBloc.close(); // the header does not close a bloc it was given
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return CometChatThreadedHeader(
      parentMessage: widget.parentMessage,
      loggedInUser: widget.loggedInUser,
      threadedHeaderBloc: _headerBloc,
    );
  }
}

Style

Dart

CometChatThreadedHeader(
  parentMessage: parentMessage,
  loggedInUser: loggedInUser,
  style: CometChatThreadedHeaderStyle(
    bubbleContainerBackGroundColor: Colors.white,
    countTextColor: Color(0xFF727272),
  ),
)

Next Steps

Message List

Display messages in a conversation

Message Composer

Compose and send messages

Threaded Messages Guide

Complete threaded messages implementation

Component Styling

Detailed styling reference

​Where It Fits

​Quick Start

​Actions and Events

​Navigation (host-owned)

​Custom message actions

​Thread subscription

​SDK Events (Real-Time, Automatic)

​Functionality

​Custom View Slots

​Bubble View

​Advanced

​BLoC Access

​Style

​Next Steps

Message List

Message Composer

Threaded Messages Guide

Component Styling

Where It Fits

Quick Start

Actions and Events

Navigation (host-owned)

Custom message actions

Thread subscription

SDK Events (Real-Time, Automatic)

Functionality

Custom View Slots

Bubble View

Advanced

BLoC Access

Style

Next Steps