feat(react-native-uikit-docs): Pin & Save, Pin Conversation and Thread Subscription

docs.json

@@ -33,7 +33,7 @@
       {
         "product": "Home",
         "pages": [
-            "index"
+          "index"
         ]
       },
       {
@@ -1208,6 +1208,8 @@
                               "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-text-color",
                               "ui-kit/react-native/guide-search-messages",
                               "ui-kit/react-native/guide-message-privately",
                               "ui-kit/react-native/guide-block-unblock-user",

ui-kit/react-native/compact-message-composer.mdx

@@ -80,7 +80,7 @@
 }
 ```
 
 #### onError
 
 Fires on internal errors (network failure, auth issue, SDK exception).
 
@@ -154,7 +154,7 @@
 
 ### Global UI Events
 
 `CometChatUIEventHandler` emits events subscribable from anywhere in the application. Add listeners and remove them on cleanup.
 
 | Event | Fires when | Payload |
 | --- | --- | --- |
@@ -221,8 +221,8 @@
 | `enableRichTextEditor` | `hideRichTextFormattingOptions` | Result |
 |------------------------|-------------------------------|--------|
 | `false` | - | Plain text, no formatting UI |
-| `true` | `true` | Toolbar always visible above input |
-| `true` | `false` | No toolbar UI, only text selection menu items work |
+| `true` (default) | `false` (default) | Toolbar visible above input |
+| `true` | `true` | No toolbar UI, only text selection menu items work |
 
 ### Text Selection Menu Items
 
@@ -251,11 +251,11 @@
 ### Toolbar Configuration Examples
 
 ```tsx lines
-// Toolbar always visible above input
+// Toolbar visible above input (the default)
 <CometChatCompactMessageComposer
   user={chatUser}
   enableRichTextEditor={true}
-  hideRichTextFormattingOptions={true}
+  hideRichTextFormattingOptions={false}
 />
 ```
 
@@ -264,6 +264,7 @@
 <CometChatCompactMessageComposer
   user={chatUser}
   enableRichTextEditor={true}
+  hideRichTextFormattingOptions={true}
   showTextSelectionMenuItems={true}
 />
 ```
@@ -286,7 +287,7 @@
 |------|------|---------|-------------|
 | `maxLines` | `number` | `5` | Maximum lines before scrolling is enabled |
 | `minInputHeight` | `number` | `40` | Minimum height for the input in pixels |
 | `maxInputHeight` | `number` | `144` (calculated from maxLines) | Maximum height for the input. Overrides `maxLines` if both provided |
 
 ```tsx lines
 <CometChatCompactMessageComposer
@@ -310,13 +311,14 @@
 | `AuxiliaryButtonView` | `({ user, group, composerId }) => JSX.Element` | Sticker button area |
 | `SecondaryButtonView` | `({ user, group, composerId }) => JSX.Element` | Attachment button area |
 | `SendButtonView` | `({ user, group, composerId }) => JSX.Element` | Send button |
+| `ToolbarTrailingButtonsView` | `({ user, group, composerId, composer }) => JSX.Element` | Adds views at the end of the formatting toolbar |
 | `attachmentOptions` | `CometChatMessageComposerAction[]` | Default attachment options list |
 | `addAttachmentOptions` | `CometChatMessageComposerAction[]` | Additional attachment options appended to defaults |
 | `textFormatters` | `CometChatTextFormatter[]` | Text formatting in composer |
 
 ### textFormatters
 
 Custom text formatters for the composer input. To configure the existing Mentions look and feel check out [CometChatMentionsFormatter](/ui-kit/react-native/mentions-formatter-guide).
 
 ```tsx lines
 import {
@@ -344,7 +346,7 @@
 );
 ```
 
 ### attachmentOptions
 
 Override the default attachment options with custom actions.
 
@@ -518,6 +520,71 @@
 );
 ```
 
+### ToolbarTrailingButtonsView
+
+Render your own buttons at the trailing end of the rich-text formatting toolbar, after the built-in buttons and a divider. This is the place for a formatting control the toolbar does not have — for example, a color button that colors the selected text.
+
+Besides `user`, `group` and `composerId`, the render function receives a **`composer`** handle (`ComposerInputHandle`) for reading and changing the input — without it a toolbar button could not act on the text.
+
+```tsx lines
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import {
+  CometChatCompactMessageComposer,
+  ComposerInputHandle,
+} from "@cometchat/chat-uikit-react-native";
+import { Text, TouchableOpacity } from "react-native";
+
+const ColorRedButton = ({ composer }: { composer: ComposerInputHandle }) => {
+  // A code block is sent as raw text, so a color applied inside one is lost.
+  const inCodeBlock = composer.getActiveStyles().codeBlock;
+
+  return (
+    <TouchableOpacity
+      accessibilityLabel="Color selected text red"
+      disabled={inCodeBlock}
+      style={{ paddingHorizontal: 8, paddingVertical: 4, opacity: inCodeBlock ? 0.4 : 1 }}
+      onPress={() => composer.applyInlineStyle("color", "#E11D48")}>
+      <Text style={{ color: "#E11D48", fontWeight: "700" }}>A</Text>
+    </TouchableOpacity>
+  );
+};
+
+function ComposerWithColor({ chatUser }: { chatUser: CometChat.User }) {
+  return (
+    <CometChatCompactMessageComposer
+      user={chatUser}
+      ToolbarTrailingButtonsView={({ composer }) => <ColorRedButton composer={composer} />}
+    />
+  );
+}
+```
+
+<Note>
+The slot lives inside the toolbar, so it only renders while the toolbar is visible — `enableRichTextEditor` `true` and `hideRichTextFormattingOptions` `false`, which are the defaults. It does not appear in the native text selection menu. For a complete walkthrough with a swatch picker, see the [Custom Text Formatter guide](/ui-kit/react-native/guide-text-color).
+</Note>
+
+<Warning>
+Render your controls inline in the toolbar rather than in a `Modal`. A modal takes focus from the input, which collapses the selection before your command runs.
+</Warning>
+
+The `composer` handle:
+
+| Method | Description |
+| --- | --- |
+| `getText()` | Current plain-text content |
+| `getSelection()` | Current selection as `{ start, end }` — collapsed when there is only a caret |
+| `setText(text)` | Replaces the content |
+| `setSelection(start, end?)` | Moves the selection; omit `end` for a caret |
+| `insertLink(url, text)` | Inserts a link, wrapping the selection when there is one |
+| `toggleBold()` / `toggleItalic()` / `toggleUnderline()` / `toggleStrikethrough()` / `toggleCode()` | Same as the built-in toolbar buttons |
+| `clearFormatting()` | Removes all inline formatting from the selection |
+| `applyInlineStyle(key, value)` | Applies `"color"` or `"backgroundColor"` (any React Native color string) to the selection, skipping mentions |
+| `removeInlineStyle(key)` | Removes that style from the selection |
+| `getMentionRanges()` | Mention ranges in plain-text positions |
+| `getActiveStyles()` | Formatting at the caret: `bold`, `italic`, `underline`, `strikethrough`, `code`, `codeBlock`, `highlight`, `blockType`, `alignment` |
+
+Only `"color"` is sent with the message, as `<color=#rrggbb>…</color>`, and the UI Kit renders it in the bubble automatically. `"backgroundColor"` styles the composer only and is dropped on send.
+
 ### HeaderView
 
 Custom view above the composer input.
@@ -645,7 +712,7 @@
 | `imageQuality` | Image quality for camera (1-100) | `imageQuality={50}` |
 | `auxiliaryButtonsAlignment` | Alignment of auxiliary buttons | `auxiliaryButtonsAlignment="right"` |
 | `enableRichTextEditor` | Enable/disable rich text formatting | `enableRichTextEditor={true}` |
-| `hideRichTextFormattingOptions` | Always-visible toolbar mode | `hideRichTextFormattingOptions={true}` |
+| `hideRichTextFormattingOptions` | Hide the formatting toolbar; formatting stays available from the text selection menu | `hideRichTextFormattingOptions={true}` |
 | `showTextSelectionMenuItems` | Formatting in native text selection menu | `showTextSelectionMenuItems={true}` |
 | `enterKeyBehavior` | Android Enter key behavior | `enterKeyBehavior={EnterKeyBehavior.SendMessage}` |
 | `maxLines` | Maximum lines before scrolling | `maxLines={3}` |

ui-kit/react-native/conversations.mdx

@@ -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 |
 
 ---
 

ui-kit/react-native/core-features.mdx

@@ -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.

ui-kit/react-native/custom-text-formatter-guide.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Custom Text Formatter"
+sidebarTitle: "Text Formatter Base Class"
 description: "Extend the CometChatTextFormatter base class to implement custom inline text patterns with regex and callbacks in React Native."
 ---
 
@@ -9,7 +10,7 @@
 | --- | --- |
 | Components | `CometChatMessageComposer`, `CometChatMessageHeader`, `CometChatMessageList` |
 | Package | `@cometchat/chat-uikit-react-native` |
 | Key class | `CometChatTextFormatter` (abstract base class for custom formatters) |
 | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")` |
 | Purpose | Extend to create custom inline text patterns with regex, styling, and callbacks |
 | Features | Text formatting, customizable styles, dynamic text replacement, suggestion list integration |
@@ -18,7 +19,7 @@
 
 </Accordion>
 
 `CometChatTextFormatter` is an abstract class for formatting text in the message composer and message bubbles. Extend it to build custom formatters — hashtags, keywords, or any regex-based pattern.
 
 | Capability | Description |
 | --- | --- |
@@ -31,7 +32,7 @@
 
 ## Base Class Overview
 
 The `CometChatTextFormatter` class provides the foundation for all text formatters in React Native:
 
 ```tsx
 import { CometChatTextFormatter } from "@cometchat/chat-uikit-react-native";
@@ -276,7 +277,7 @@
 
 ## Advanced: Suggestion List Integration
 
 For formatters that need to show suggestions (like mentions), implement the `search` method:
 
 ```tsx
 import { CometChat } from "@cometchat/chat-sdk-react-native";

ui-kit/react-native/guide-overview.mdx

@@ -32,7 +32,8 @@ Use these guides after completing the base [Getting Started](/ui-kit/react-nativ
 | [Threaded Messages](/ui-kit/react-native/guide-threaded-messages) | Threaded replies: open parent context, list replies, compose within focused thread. |
 | [Search Messages](/ui-kit/react-native/guide-search-messages) | Add full‑text message search across conversations with result routing into context. |
 | [Block/Unblock User](/ui-kit/react-native/guide-block-unblock-user) | Let users block or unblock others in 1:1 chats; hides composer and shows an unblock prompt. |
-| [Custom Text Formatter](/ui-kit/react-native/custom-text-formatter-guide) | Extend the base formatter to implement custom inline patterns (hashtags, keywords) with regex + callbacks. |
+| [Custom Text Formatter](/ui-kit/react-native/guide-text-color) | Add a color button to the composer toolbar that colors selected text, rendered in the sent message. |
+| [Text Formatter Base Class](/ui-kit/react-native/custom-text-formatter-guide) | Extend the base formatter to implement custom inline patterns (hashtags, keywords) with regex + callbacks. |
 | [Mentions Formatter](/ui-kit/react-native/mentions-formatter-guide) | Add @mentions with styled tokens, suggestion list, and click handling for users & members. |
 | [URL Formatter](/ui-kit/react-native/url-formatter-guide) | Detect and style plain URLs, emails, and phone numbers as clickable links. |
 | [Shortcut Formatter](/ui-kit/react-native/shortcut-formatter-guide) | Provide !shortcut style expansions invoking extension APIs before inserting content. |