cometchat · suraj-chauhan-cometchat · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026 · Sep 10, 2026
diff --git a/docs.json b/docs.json
@@ -33,7 +33,7 @@
       {
         "product": "Home",
         "pages": [
-            "index"
+          "index"
         ]
       },
       {
@@ -1208,6 +1208,7 @@
                               "ui-kit/react-native/guide-new-chat",
                               "ui-kit/react-native/guide-group-chat",
                               "ui-kit/react-native/guide-threaded-messages",
+                              "ui-kit/react-native/guide-pin-and-save-messages",
                               "ui-kit/react-native/guide-search-messages",
                               "ui-kit/react-native/guide-message-privately",
                               "ui-kit/react-native/guide-block-unblock-user",

diff --git a/images/pin.png b/images/pin.png
diff --git a/images/save.png b/images/save.png
@@ -28,14 +28,14 @@
    "callbacks": {
      "onItemPress": "(conversation: CometChat.Conversation) => void",
      "onItemLongPress": "(conversation: CometChat.Conversation) => void",
      "onBack": "() => void",
      "onSelection": "(conversations: Array<CometChat.Conversation>) => void",
      "onError": "(error: CometChat.CometChatException) => void",
      "onEmpty": "() => void",
      "onLoad": "(list: CometChat.Conversation[]) => void",
      "onSearchBarClicked": "() => void",
      "onSearchTextChanged": "(searchText: string) => void",
      "onSubmit": "(conversations: Array<CometChat.Conversation>) => void"
    },
    "visibility": {
      "hideBackButton": { "type": "boolean", "default": true },
@@ -74,7 +74,7 @@
      "SearchView": "() => JSX.Element"
    },
    "formatting": {
      "textFormatters": {
        "type": "CometChatTextFormatter[]",
        "default": "default formatters from data source"
      }
@@ -287,7 +287,7 @@
 }
 ```

 #### onSelection

 Fires when conversations are selected/deselected in selection mode. Requires `selectionMode` to be set.

@@ -309,7 +309,7 @@
 }
 ```

 #### onError

 Fires on internal errors (network failure, auth issue, SDK exception).

@@ -328,7 +328,7 @@
 }
 ```

 #### onEmpty

 Fires when the conversation list is empty.

@@ -344,7 +344,7 @@
 }
 ```

 #### onLoad

 Fires when the list is successfully fetched and loaded.

@@ -363,7 +363,7 @@

 ### Global UI Events

 `CometChatUIEventHandler` emits events subscribable from anywhere in the application. Subscribe in a `useEffect` and unsubscribe on cleanup.

 | Event | Fires when | Payload |
 | --- | --- | --- |
@@ -417,36 +417,15 @@
 nobody else sees it — and it syncs to that user's other devices.
 
 <Warning>
-  **Off by default, and it needs a server flag that is not seeded.** Pin Conversation requires
+  **Pin Conversation needs a server flag that is not seeded.** It requires
   `features.ux.conversations.pinned.enabled`, which ships enabled in no plan and must be mapped per
-  app. Until then every attempt rejects with `ERR_FEATURE_NOT_ACCESSIBLE`. On top of that, the kit
-  needs your own opt-in via `PinConversationConfig.enable(true)`.
+  app. Until then the option never renders, and a direct SDK call rejects with
+  `ERR_FEATURE_NOT_ACCESSIBLE`. The UI Kit reads that flag itself at login and on every reconnect —
+  there is no app code to write.
 </Warning>
 
-<Tabs>
-<Tab title="TypeScript">
-```typescript
-import { PinConversationConfig } from "@cometchat/chat-uikit-react-native";
-
-// Once, at app start — defaults to off
-PinConversationConfig.enable(true);
-```
-
-</Tab>
-
-<Tab title="JavaScript">
-```javascript
-import { PinConversationConfig } from "@cometchat/chat-uikit-react-native";
-
-PinConversationConfig.enable(true);
-```
-
-</Tab>
-
-</Tabs>
-
 `pinConversationOptionVisibility` (default `true`) hides the option on one particular list. It is
-**ANDed** with the global config, so the option renders only when both allow it.
+**ANDed** with the Dashboard flag, so the option renders only when both allow it.
 
 <Tabs>
 <Tab title="TypeScript">
@@ -811,7 +790,7 @@
 }
 ```

 ### addOptions

 Extends the default context menu actions with additional options.

@@ -839,7 +818,7 @@
 }
 ```

 ### datePattern

 Custom date format for displaying timestamps.

@@ -867,13 +846,13 @@
    return `${day}, ${hours}:${minutes}`;
  };

  return <CometChatConversations datePattern={generateDateString} />;
 }
 ```

 ### textFormatters

 Custom text formatters for the conversation subtitle.

 <Frame>
  <img src="/images/55490fa9-mentions_conversations-1a7b847ad0af53848dc106216ac64e74.png" />
@@ -940,11 +919,11 @@
 function MinimalConversations() {
  return (
    <CometChatConversations
      receiptsVisibility={false}
      usersStatusVisibility={false}
      groupTypeVisibility={false}
      deleteConversationOptionVisibility={false}
      hideHeader={true}
    />
  );
 }
@@ -1149,7 +1128,7 @@

 ---

 ### hideError

 Hides the error state view.

@@ -1298,7 +1277,7 @@

 | | |
 | --- | --- |
 | Type | `(searchText: string) => void` |
 | Default | `undefined` |

 ---
@@ -1316,7 +1295,7 @@

 ### onSubmit

 Callback fired when the submit button is pressed. Requires `selectionMode` to be set.

 | | |
 | --- | --- |
@@ -1393,12 +1372,12 @@

 ### textFormatters

 Custom text formatters for the conversation subtitle.

 | | |
 | --- | --- |
 | Type | `CometChatTextFormatter[]` |
 | Default | Default formatters from data source |

 ---


@@ -147,6 +147,34 @@
 | [MessageComposer](/ui-kit/react-native/message-composer) | [MessageComposer](/ui-kit/react-native/message-composer) component allows users to compose and send various types of messages, including support for the Mentions feature to directly address participants within the conversation.                       |
 | [MessageList](/ui-kit/react-native/message-list)         | [MessageList](/ui-kit/react-native/message-list) component displays a list of sent and received messages. It also supports rendering Mentions, enhancing the clarity and interactivity of conversations by highlighting direct references to users.       |
 
+## Pin and Save Messages
+
+CometChat lets users **pin** important messages so they're highlighted for everyone in a conversation, and **save** messages privately to a personal list that spans every conversation. Pinned and saved messages show an indicator on the bubble, and dedicated screens let users review them.
+
+| Components | Functionality |
+| --- | --- |
+| [Message List](/ui-kit/react-native/message-list) | Adds Pin, Unpin, Save, and Unsave to the message options when the features are enabled. |
+| [Pinned Messages](/ui-kit/react-native/pinned-messages) | A screen of the messages pinned in a conversation, opened from the [Message Header](/ui-kit/react-native/message-header). |
+| [Saved Messages](/ui-kit/react-native/saved-messages) | A personal screen of the current user's saved messages across all conversations. |
+
+Your app can also cap how many items a user may pin or save through three app settings:
+
+| App setting | Caps |
+| --- | --- |
+| features.ux.messages.pinned.limit | Pinned messages per conversation |
+| features.ux.messages.saved.limit | Saved messages per user |
+| features.ux.conversations.pinned.limit | Pinned conversations per user |
+
+The UI Kit reads these settings at login. When a user reaches a cap, the kit shows a toast that names the exact limit — no extra handling required. For a full walkthrough, see the [Pin & Save Messages guide](/ui-kit/react-native/guide-pin-and-save-messages).
+
+## Pin Conversations
+
+Keep the chats that matter at the top. Users pin a conversation from the long-press menu; pinned conversations show a pin indicator and stay above the rest of the list.
+
+| Component | Role |
+| --- | --- |
+| [CometChatConversations](/ui-kit/react-native/conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. |
+
 ## Rich Text Formatting
 
 Rich Text Formatting allows users to style their messages with bold, italic, underline, strikethrough, code, links, lists, blockquotes, and code blocks. This brings richer expression to conversations and helps users emphasize key points.
@@ -236,6 +264,17 @@
 | [MessageComposer](/ui-kit/react-native/message-composer)         | [MessageComposer](/ui-kit/react-native/message-composer) component enables users to compose and send various types of messages.                                                                                                                           |
 | [MessageList](/ui-kit/react-native/message-list)                 | [MessageList](/ui-kit/react-native/message-list) component displays a chronological list of sent and received messages. It also supports Mentions, making conversations more interactive and easier to follow by highlighting direct references to users. |
 
+### Thread Subscription
+
+Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Enabled by default — remove a surface with `hideThreadSubscriptionOption` or `threadSubscriptionVisibility`.
+
+| Component | Role |
+| --- | --- |
+| [CometChatMessageList](/ui-kit/react-native/message-list) | Provides the Subscribe to thread / Unsubscribe from thread option in the message action sheet. |
+| [CometChatMessageHeader](/ui-kit/react-native/message-header) | Shows the subscription bell on the thread view. |
+
+See the [Thread Subscription guide](/ui-kit/react-native/guide-threaded-messages#thread-subscription) for setup and behavior.
+
 ## Group Chat
 
 CometChat facilitates Group Chats, allowing users to have conversations with multiple participants simultaneously. This feature is crucial for team collaborations, group discussions, social communities, and more.

@@ -0,0 +1,252 @@
+---
+title: "Pin & Save Messages"
+sidebarTitle: "Pin & Save Messages"
+description: "Let users pin important messages for everyone in a conversation and save messages privately for themselves."
+---
+
+## Goal
+
+By the end of this guide you will have a chat screen where users can **pin** a message so it's highlighted for everyone in the conversation, open a screen of all pinned messages, and **save** a message privately to their own list — with a dedicated "Saved" screen to review saves across every conversation.
+
+Pin and save are two separate concepts:
+
+| | Pin | Save |
+| --- | --- | --- |
+| **Visible to** | Everyone in the conversation | Only the current user |
+| **Scope** | One conversation | All conversations |
+| **Surfaced by** | `CometChatPinnedMessages` (per conversation) | `CometChatSavedMessages` (a personal screen) |
+| **Opened from** | The message header's pinned-messages button | Your own navigation (no built-in trigger) |
+
+## Prerequisites
+
+- Completed the [Integration Guide](/ui-kit/react-native/react-native-cli-integration)
+- An existing chat screen using `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer`
+- **Pin messages** and **Save messages** enabled for your app through the `features.ux.messages.pinned.enabled` and `features.ux.messages.saved.enabled` app settings. See [Core Features → Pin & Save](/ui-kit/react-native/core-features#pin-and-save-messages).
+
+<Note>
+The pin/unpin and save/unsave options only appear in the message options when the corresponding feature is enabled for your app. The UI Kit reads that setting at login and re-reads it on every reconnection, so no extra wiring is needed to show or hide the options.
+</Note>
+
+## Step 1: The Message Options
+
+Once the features are enabled, `CometChatMessageList` automatically adds **Pin**, **Unpin**, **Save**, and **Unsave** to the message options — no props required. You only need the `hide*` props if you want to remove one:
+
+_File: Messages.tsx_
+
+```tsx
+import { CometChatMessageList } from "@cometchat/chat-uikit-react-native";
+
+<CometChatMessageList
+  user={user}
+  group={group}
+  // Options are shown by default; pass hide* props only to remove them:
+  // hidePinMessageOption={true}
+  // hideUnpinMessageOption={true}
+  // hideSaveMessageOption={true}
+  // hideUnsaveMessageOption={true}
+/>
+```
+
+The **Pin/Unpin option is shown to every member** — the UI Kit does not gate it by role. Permission is enforced by the **server**: if a member isn't allowed to pin or unpin in that conversation, the action is rejected and the UI Kit shows a permission toast. Saving is per-user and always available.
+
+<Note>
+The options are hidden on messages the server would refuse anyway — an unsent message with no ID yet, a deleted message, or one still awaiting a moderation verdict. A message sent seconds ago may briefly show no pin or save option while moderation is pending; it appears once the message is approved.
+</Note>
+
+## Step 2: Open the Pinned Messages Screen
+
+`CometChatMessageHeader` can show a pinned-messages button. Set `showPinnedMessagesButton` and wire `onPinnedMessagesPress` to navigate to `CometChatPinnedMessages`, scoped to the same `user`/`group`.
+
+_File: Messages.tsx_
+
+```tsx
+import { CometChatMessageHeader } from "@cometchat/chat-uikit-react-native";
+
+<CometChatMessageHeader
+  user={user}
+  group={group}
+  showPinnedMessagesButton={true}
+  onPinnedMessagesPress={() =>
+    navigation.navigate("PinnedMessages", { user, group })
+  }
+/>
+```
+
+_File: PinnedMessages.tsx_
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatPinnedMessages } from "@cometchat/chat-uikit-react-native";
+import { useNavigation, useRoute } from "@react-navigation/native";
+import { SafeAreaView } from "react-native";
+
+const PinnedMessages = () => {
+  const navigation = useNavigation<any>();
+  const route = useRoute<any>();
+  const { user, group } = route.params ?? {};
+
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <CometChatPinnedMessages
+        user={user}
+        group={group}
+        onBack={() => navigation.goBack()}
+        onItemPress={(message: CometChat.BaseMessage) => {
+          // Jump the main message list to this message.
+          navigation.navigate("Messages", {
+            user,
+            group,
+            messageId: String(message.getId()),
+          });
+        }}
+      />
+    </SafeAreaView>
+  );
+};
+
+export default PinnedMessages;
+```
+
+`CometChatPinnedMessages` is **per conversation** — it takes the same `user` or `group` the chat screen was opened with, and lists that conversation's pinned messages newest-pin first.
+
+<Frame>
+  <img
+    src="/images/pin.png"
+    alt="The Pinned Messages screen listing one conversation's pinned messages as full bubbles, each with a pin glyph beside its timestamp."
+  />
+</Frame>
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `user` | `CometChat.User` | 1-1 conversation. Mutually exclusive with `group`. |
+| `group` | `CometChat.Group` | Group conversation. Mutually exclusive with `user`. |
+| `limit` | `number` | Page size. Defaults to 30; the server caps a conversation at 100. |
+| `onBack` | `() => void` | Closes the screen — rendered as the back control in the header. |
+| `onItemPress` | `(message) => void` | Tapping a row, so the host can jump its message list to that message. |
+
+## Step 3: Add a "Saved" Screen
+
+`CometChatSavedMessages` is **user-level**, not per conversation — it lists everything the logged-in user has saved, across every chat. There is no built-in entry point, so open it from your own navigation: a menu item, a profile screen, or a tab.
+
+<Frame>
+  <img
+    src="/images/save.png"
+    alt="The Saved Messages screen listing saved messages from across every conversation, each row showing its source conversation and a one-line preview."
+  />
+</Frame>
+
+_File: SavedMessages.tsx_
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatSavedMessages } from "@cometchat/chat-uikit-react-native";
+import { useNavigation } from "@react-navigation/native";
+import { SafeAreaView } from "react-native";
+
+const SavedMessages = () => {
+  const navigation = useNavigation<any>();
+
+  return (
+    <SafeAreaView style={{ flex: 1 }}>
+      <CometChatSavedMessages
+        onBack={() => navigation.goBack()}
+        onItemPress={async (message, source) => {
+          if (!source) return;
+          // `source` names the conversation as an id + type, so resolve it to the
+          // object the chat screen expects before navigating.
+          const party =
+            source.receiverType === "group"
+              ? { group: await CometChat.getGroup(source.receiverId) }
+              : { user: await CometChat.getUser(source.receiverId) };
+
+          navigation.navigate("Messages", {
+            ...party,
+            messageId: String(message.getId()),
+          });
+        }}
+      />
+    </SafeAreaView>
+  );
+};
+
+export default SavedMessages;
+```
+
+Each row shows which conversation the message came from, so a saved message is never orphaned from its context. `source` carries that conversation as `receiverType` (`"user"` or `"group"`) and `receiverId`, plus `name`, `label` and an optional `avatar` — see the [component reference](/ui-kit/react-native/saved-messages#onitempress).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `limit` | `number` | Page size. Defaults to 30; the server caps the whole set at 100. |
+| `onBack` | `() => void` | Closes the screen. |
+| `onItemPress` | `(message, source) => void` | Receives the message and its resolved source conversation. |
+
+## Step 4: Pinned & Saved Indicators
+
+No wiring needed. `CometChatMessageList` renders a pin glyph and a filled bookmark in the message's meta row, beside the timestamp, and keeps them in sync in real time:
+
+- **Pin** is conversation-wide, so every participant sees the indicator appear and disappear as the message is pinned or unpinned.
+- **Save** is private, so the indicator appears only for the user who saved it — and syncs to that user's **other devices**.
+
+## Step 5: Limits
+
+Both features are capped by the server, per app:
+
+| Limit | Applies to |
+| --- | --- |
+| Pinned messages | Per conversation |
+| Saved messages | Per user, across all conversations |
+
+When a cap is reached, the action is rejected and the UI Kit shows a toast carrying the **server-provided limit** — the number is never hard-coded in the kit, so raising the cap for your app changes the message automatically.
+
+## Complete Example
+
+_File: Messages.tsx_
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import {
+  CometChatMessageComposer,
+  CometChatMessageHeader,
+  CometChatMessageList,
+} from "@cometchat/chat-uikit-react-native";
+import { useNavigation, useRoute } from "@react-navigation/native";
+import { View } from "react-native";
+
+const Messages = ({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => {
+  const navigation = useNavigation<any>();
+  const route = useRoute<any>();
+  // Set when this screen was opened from the Pinned or Saved list.
+  const goToMessageId = route.params?.messageId;
+
+  return (
+    <View style={{ flex: 1 }}>
+      <CometChatMessageHeader
+        user={user}
+        group={group}
+        showPinnedMessagesButton={true}
+        onPinnedMessagesPress={() =>
+          navigation.navigate("PinnedMessages", { user, group })
+        }
+      />
+
+      <View style={{ flex: 1 }}>
+        <CometChatMessageList user={user} group={group} goToMessageId={goToMessageId} />
+      </View>
+
+      <CometChatMessageComposer user={user} group={group} />
+    </View>
+  );
+};
+
+export default Messages;
+```
+
+`goToMessageId` is what makes the jump actually happen: `CometChatMessageList` fetches the page around that ID and scrolls to it, so tapping a pinned or saved row lands on the message in its original conversation.
+
+## Next Steps
+
+- [CometChatPinnedMessages](/ui-kit/react-native/pinned-messages) — the full component reference
+- [CometChatSavedMessages](/ui-kit/react-native/saved-messages) — the full component reference
+- [Pin Message (SDK)](/sdk/react-native/pin-message) — the underlying SDK methods and listeners
+- [Save Message (SDK)](/sdk/react-native/save-message)
+- [Pin Conversation](/ui-kit/react-native/core-features#pin-conversations) — pinning a whole chat to the top of the list