> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pinned Messages

> A screen listing every pinned message in one conversation, with long-press unpin and tap-to-jump.

<Accordion title="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](#actions-and-events) |
  | 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](#functionality) |
</Accordion>

<Note>
  **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.
</Note>

`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](/docs/ui-kit/flutter/message-header#pinned-messages) 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.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatPinnedMessages.show(
      context,
      group: group, // or: user: user
      onItemTap: (message) => _controller.jumpToMessage(message.id),
    );
    ```
  </Tab>
</Tabs>

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`](/docs/ui-kit/flutter/message-list#jump-to-a-message) to land on the message without remounting the list.

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatPinnedMessages(
      group: group,
      onItemTap: (BaseMessage message) {
        _controller.jumpToMessage(message.id);
      },
    )
    ```
  </Tab>
</Tabs>

### 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.* |

<Tabs>
  <Tab title="Dart">
    ```dart theme={null}
    CometChatPinnedMessages(
      group: group,
      style: CometChatPinnedMessagesStyle(
        backgroundColor: Colors.white,
        separatorColor: Colors.grey.shade300,
        unpinIconColor: Colors.redAccent, // v6.2.0 and later
      ),
    )
    ```
  </Tab>
</Tabs>

<Note>
  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.
</Note>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Pin & Save Messages Guide" icon="thumbtack" href="/docs/ui-kit/flutter/guide-pin-and-save-messages">
    Wire the pinned and saved screens into your app
  </Card>

  <Card title="Saved Messages" icon="bookmark" href="/docs/ui-kit/flutter/saved-messages">
    The logged-in user's private saved list
  </Card>

  <Card title="Message List" icon="list" href="/docs/ui-kit/flutter/message-list#pin-or-save-a-message">
    The Pin / Unpin options and jump-to-message
  </Card>

  <Card title="Pin A Message (SDK)" icon="code" href="/docs/sdk/flutter/pin-message">
    The SDK APIs underneath
  </Card>
</CardGroup>


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