Pinned Messages - CometChat Docs

AI Integration Quick Reference

Field	Value
Component	`CometChatPinnedMessages`
Package	`cometchat_chat_uikit`
Import	`import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';`
Purpose	A screen listing every pinned message in one conversation, with long-press unpin and tap-to-jump.
Data props	`user` · `group`
Actions	`onItemTap` — details
Presentation	`CometChatPinnedMessages.show(context, ...)` pushes it on the nearest `Navigator`; or embed the widget directly.
Styling	`style` — the app `ThemeData` does not reach inside a kit widget, so scope colours here.
Prerequisites	`CometChatUIKit` initialised, a user logged in, and the Pin Message feature enabled for the app.
Full props	7 props

Available from UI Kit v6.1.1. This component requires cometchat_chat_uikit v6.1.1 or later, which depends on cometchat_sdk v5.0.7.

CometChatPinnedMessages lists the pinned messages of a single conversation. Each row renders the message as a read-only bubble, ordered newest-pinned-first. Tapping a row reports it through onItemTap so the host can jump its message list to that message, and long-pressing a row offers Unpin behind a confirmation dialog.

Where It Fits

The screen opens on the nearest Navigator, the same navigation threads use. On a desktop side-by-side layout that replaces only the chat column; on mobile it is a full-screen route. The usual entry point is the Pinned Messages item in CometChatMessageHeader’s ⋯ overflow menu, which pushes this screen for you. See Message Header for the props that control it.

Quick Start

Either call the show helper, which pushes the screen with the kit’s own transition, or embed the widget directly.

Dart

CometChatPinnedMessages.show(
  context,
  group: group, // or: user: user
  onItemTap: (message) => _controller.jumpToMessage(message.id),
);

Pass one of user or group — the constructor asserts that at least one is set.

Actions and Events

Callback Methods

`onItemTap`

Fires when a row is tapped. When showBackButton is true (the default), the screen asks its route to pop first, so the host lands on the message with the list already gone. Pair it with CometChatMessageListController.jumpToMessage to land on the message without remounting the list.

Dart

CometChatPinnedMessages(
  group: group,
  onItemTap: (BaseMessage message) {
    _controller.jumpToMessage(message.id);
  },
)

Unpin

Long-pressing a row opens an Unpin message? confirmation, then unpins the message and shows a “Message unpinned” toast. The kit does not decide who may unpin — the server does. A rejected call (ERR_PERMISSION_DENIED, ERR_UNAUTHORIZED or ERR_FORBIDDEN) shows “You don’t have permission to perform this action.” Set hideUnpinOption: true to turn the long-press off.

Real-Time Updates (Automatic)

The list stays current without a refetch. No setup needed.

Source	Internal behavior
`ccMessagePinned` / `ccMessageUnpinned` (UI Kit events)	Adds or drops the row for actions taken elsewhere in the app
`onMessagePinned` / `onMessageUnpinned` (SDK listener)	Reflects pins and unpins made by other members
Message edited, moderated, saved or unsaved	Refreshes the row in place
Message deleted	Drops the row

The list is fetched once on open, 100 at a time until exhausted, with a Retry action if the fetch fails and an empty state (“No pinned messages yet”) when there are none.

Functionality

Property	Type	Default	Description
`user`	`User?`	`null`	One-on-one conversation scope. Pass this or `group`.
`group`	`Group?`	`null`	Group conversation scope. Pass this or `user`.
`onItemTap`	`Function(BaseMessage message)?`	`null`	Fires on row tap, after the screen asks to pop (when `showBackButton` is `true`).
`hideUnpinOption`	`bool?`	`null`	Turns off long-press unpin on the rows.
`showBackButton`	`bool`	`true`	Shows the app bar’s back arrow, and makes a row tap pop the screen. Set it to `false` when the list is embedded in a host-owned panel — the tap then leaves the host’s route alone.
`hideAppBar`	`bool`	`false`	Drops the header entirely. Set it when the host already renders a title bar — a desktop side panel does, and two stacked headers is the result otherwise.
`style`	`CometChatPinnedMessagesStyle?`	`null`	Styling overrides.

The show helper takes the same parameters after context. When the Message Header opens the screen for you, it forwards only user, group, onItemTap (from onPinnedMessageItemTap) and style (from pinnedMessagesStyle) — to set hideUnpinOption or the layout flags, handle onPinnedMessagesTap and call show yourself.

Style

Rows are real message bubbles, so they follow your bubble styling. CometChatPinnedMessagesStyle styles the screen around them:

Property	Applies to
`backgroundColor`	The screen background
`appBarColor`	The app bar background. Applied since v6.2.0.
`titleTextStyle`	The “Pinned Messages” title
`iconColor`	The back arrow
`separatorColor`	The divider under the app bar
`unpinIconColor`	The pin icon in the unpin confirmation dialog. Applied since v6.2.0.

Dart

CometChatPinnedMessages(
  group: group,
  style: CometChatPinnedMessagesStyle(
    backgroundColor: Colors.white,
    separatorColor: Colors.grey.shade300,
    unpinIconColor: Colors.redAccent, // v6.2.0 and later
  ),
)

On v6.1.1, appBarColor and unpinIconColor are declared but have no visible effect — upgrade to v6.2.0 to use them. The class also declares itemTitleTextStyle, itemSubtitleTextStyle, itemDateTextStyle and borderRadius, which no release up to v6.2.0 applies, because rows are drawn as message bubbles.

Next Steps

Pin & Save Messages Guide

Wire the pinned and saved screens into your app

Saved Messages

The logged-in user’s private saved list

Message List

The Pin / Unpin options and jump-to-message

Pin A Message (SDK)

The SDK APIs underneath

​Where It Fits

​Quick Start

​Actions and Events

​Callback Methods

​onItemTap

​Unpin

​Real-Time Updates (Automatic)

​Functionality

​Style

​Next Steps

Pin & Save Messages Guide

Saved Messages

Message List

Pin A Message (SDK)

Where It Fits

Quick Start

Actions and Events

Callback Methods

`onItemTap`

Unpin

Real-Time Updates (Automatic)

Functionality

Style

Next Steps