Pinned Messages - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatPinnedMessages",
  "package": "@cometchat/chat-uikit-react-native",
  "import": "import { CometChatPinnedMessages } from \"@cometchat/chat-uikit-react-native\";",
  "description": "Lists the messages pinned in a conversation, newest pin first. A pin is conversation-wide and visible to everyone.",
  "requires": {
    "dashboardFlag": "Pin Messages must be enabled for your app in the CometChat Dashboard",
    "resolution": "The kit reads the flag at login and on every reconnect — no app code required. Force a re-read with refreshPinSaveFeatures()"
  },
  "props": {
    "data": {
      "user": { "type": "CometChat.User", "default": "undefined", "note": "Scopes the panel to a one-on-one conversation. Mutually exclusive with group" },
      "group": { "type": "CometChat.Group", "default": "undefined", "note": "Scopes the panel to a group. Mutually exclusive with user" },
      "limit": { "type": "number", "default": 30, "note": "Page size for the fetch; the SDK caps it at 100" }
    },
    "callbacks": {
      "onBack": "() => void",
      "onItemPress": "(message: CometChat.BaseMessage) => void"
    },
    "visibility": {
      "hideUnpinMessageOption": { "type": "boolean", "default": false },
      "hideSaveMessageOption": { "type": "boolean", "default": false },
      "hideUnsaveMessageOption": { "type": "boolean", "default": false },
      "hideCopyMessageOption": { "type": "boolean", "default": false },
      "hideShareMessageOption": { "type": "boolean", "default": false },
      "hideMessageInfoOption": { "type": "boolean", "default": false }
    },
    "customization": {
      "ItemView": "(message: CometChat.BaseMessage) => JSX.Element",
      "title": { "type": "string", "default": "localized" },
      "style": "DeepPartial<PinnedMessagesStyle>"
    }
  },
  "helpers": {
    "isPinned": "(message) => boolean",
    "isSystemPin": "(message) => boolean — pinnedBy is SYSTEM_PINNER (\"app_system\")"
  }
}

CometChatPinnedMessages lists the messages pinned in one conversation, newest pin first. A pin is conversation-wide and visible to everyone, so this panel shows the same set to every participant.

Pin Messages must be enabled for your app in the CometChat Dashboard. Until it is, the pin options never render and this panel has nothing to show. The UI Kit reads that flag itself at login and on every reconnect — there is no app code to write.

Where It Fits

Open it from the message header or an overflow menu, scoped to the conversation the user is in. It is a full-screen panel with its own back affordance rather than an inline strip.

Minimal Render

Pass exactly one of user or group — the panel is scoped to a single conversation.

TypeScript (User)
TypeScript (Group)

import { CometChatPinnedMessages } from "@cometchat/chat-uikit-react-native";

<CometChatPinnedMessages
  user={user}
  onBack={() => navigation.goBack()}
  onItemPress={(message: CometChat.BaseMessage) => scrollToMessage(message)}
/>

import { CometChatPinnedMessages } from "@cometchat/chat-uikit-react-native";

<CometChatPinnedMessages
  group={group}
  onBack={() => navigation.goBack()}
  onItemPress={(message: CometChat.BaseMessage) => scrollToMessage(message)}
/>

Enabling the feature

Pin and Save are gated on your app’s Dashboard settings. The UI Kit resolves those flags at login and on every reconnect and switches the options on or off accordingly, so there is nothing to call at start-up. PinSaveConfig is exported for the cases where you need to read or override that resolved state — not as a switch you must throw.

TypeScript
JavaScript

import {
  PinSaveConfig,
  refreshPinSaveFeatures,
  getPinSaveFeatures,
} from "@cometchat/chat-uikit-react-native";

// Read what the kit resolved from the Dashboard flags
const features = getPinSaveFeatures();

// Force a re-read after flipping a flag in the dashboard, without a re-login
await refreshPinSaveFeatures();

import {
  PinSaveConfig,
  refreshPinSaveFeatures,
  getPinSaveFeatures,
} from "@cometchat/chat-uikit-react-native";

const features = getPinSaveFeatures();
refreshPinSaveFeatures();

You do not need to fetch these flags yourself, and you do not need to enable the feature in code. The kit resolves them at login and after every reconnect. refreshPinSaveFeatures() exists for the case where an admin flips a flag in the Dashboard while the app is running.

Props

Property	Type	Default	Description
`user`	`CometChat.User`	—	Scopes the panel to a one-on-one conversation. Mutually exclusive with `group`.
`group`	`CometChat.Group`	—	Scopes the panel to a group. Mutually exclusive with `user`.
`limit`	`number`	`30`	Page size for the fetch. The SDK rejects a value above 100.
`onBack`	`() => void`	—	Called when the back affordance is pressed.
`onItemPress`	`(message) => void`	—	Called when a row is pressed — use it to jump to the message in the list.
`hideUnpinMessageOption`	`boolean`	`false`	Hides Unpin in the row menu.
`hideSaveMessageOption`	`boolean`	`false`	Hides Save in the row menu.
`hideUnsaveMessageOption`	`boolean`	`false`	Hides Unsave in the row menu.
`hideCopyMessageOption`	`boolean`	`false`	Hides Copy.
`hideShareMessageOption`	`boolean`	`false`	Hides Share.
`hideMessageInfoOption`	`boolean`	`false`	Hides Message Info.
`ItemView`	`(message) => JSX.Element`	—	Replaces the default row entirely.
`title`	`string`	localized	Panel title.
`style`	`DeepPartial<PinnedMessagesStyle>`	—	Style overrides.

Reading pin state yourself

The kit exports helpers so a custom ItemView does not have to reimplement them. The SDK has no isPinned() of its own — these are UI Kit conveniences over getPinnedAt() and getPinnedBy().

TypeScript
JavaScript

import { isPinned, isSystemPin, SYSTEM_PINNER } from "@cometchat/chat-uikit-react-native";

if (isPinned(message)) {
  // Pinned by somebody in this conversation
}

if (isSystemPin(message)) {
  // An admin/global pin — pinnedBy is SYSTEM_PINNER ("app_system"), not a real member
}

import { isPinned, isSystemPin } from "@cometchat/chat-uikit-react-native";

if (isPinned(message)) {
  // Pinned by somebody in this conversation
}

if (isSystemPin(message)) {
  // An admin/global pin
}

Actions and Events

The panel keeps itself current from the kit’s event bus, so a pin made anywhere — this screen, the message list, or another participant’s device — lands here without a manual refresh.

Event	Fires when
`ccMessagePinned` / `ccMessageUnpinned`	This device pinned or unpinned.
`ccMessageSaved` / `ccMessageUnsaved`	This device saved or unsaved.
`onMessagePinned` / `onMessageUnpinned`	Another participant pinned or unpinned — broadcast to everyone.
`onMessageSaved` / `onMessageUnsaved`	The same user saved on another device — private multi-device.

Removing asks, adding does not. Unpin and Unsave show a confirmation; Pin and Save run immediately. This is deliberate and consistent across all CometChat UI Kits — the additive action has its own undo one tap away, the destructive one does not.

Common Patterns

Jump to the pinned message

TypeScript
JavaScript

<CometChatPinnedMessages
  group={group}
  onItemPress={(message: CometChat.BaseMessage) => {
    navigation.goBack();
    scrollToMessageId(message.getId());
  }}
/>

<CometChatPinnedMessages
  group={group}
  onItemPress={(message) => {
    navigation.goBack();
    scrollToMessageId(message.getId());
  }}
/>

Read-only panel

TypeScript
JavaScript

<CometChatPinnedMessages
  group={group}
  hideUnpinMessageOption
  hideSaveMessageOption
  hideUnsaveMessageOption
/>

<CometChatPinnedMessages
  group={group}
  hideUnpinMessageOption
  hideSaveMessageOption
  hideUnsaveMessageOption
/>

Next Steps

Saved Messages

The private, cross-conversation counterpart

Message List

Where the Pin and Save options are raised

Pin A Message (SDK)

The SDK methods underneath this component

Events

Every UI Kit event, in one place

​Where It Fits

​Minimal Render

​Enabling the feature

​Props

​Reading pin state yourself

​Actions and Events

​Common Patterns

​Jump to the pinned message

​Read-only panel

​Next Steps

Saved Messages

Message List

Pin A Message (SDK)

Events

Where It Fits

Minimal Render

Enabling the feature

Props

Reading pin state yourself

Actions and Events

Common Patterns

Jump to the pinned message

Read-only panel

Next Steps