From 880093fe2e7097a57007ef04173b526b90b3fc33 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 16:07:01 +0530 Subject: [PATCH 01/18] feat(react-native-uikit-docs): pin & save, pin conversation and thread subscription MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The React Native UI Kit shipped Pin Message, Save Message, Pin Conversation and Thread Subscription in v5.5.0, but the docs only covered the two panel components. This brings React Native to parity with the Android and React kits. Core features (ui-kit/react-native/core-features.mdx) Three sections, placed in the same order Android uses: Mentions -> Pin & Save Messages -> Pin Conversations -> Rich Text Formatting Threaded Conversations -> Thread Subscription -> Group Chat Thread Subscription sits directly after Threaded Conversations, matching Android. New guides guide-pin-and-save-messages.mdx modelled on the React guide guide-thread-subscription.mdx modelled on the Android guide Both are wired into docs.json in Android's relative order — threaded-messages, then thread-subscription, then pin-and-save. Thread header component (threaded-messages-header.mdx) Adds a Thread Subscription section, mirroring the React thread-header page. Two platform differences are documented rather than copied over: * The bell is on CometChatMessageHeader, NOT CometChatThreadHeader. React puts its toggle on the thread header; the landed React Native design places it in the thread screen's top bar, driven by `parentMessage` + `threadSubscriptionVisibility`. CometChatThreadHeader's TrailingView is the escape hatch for a custom control there and does not host the bell. * Thread Subscription is ON by default on React Native and has no dashboard flag, so it is documented as opt-OUT via ThreadSubscriptionConfig.setEnabled(false). Android documents the same feature as opt-in because its default differs. The text matches what v5.5.0 actually ships and the published release notes. Pin is documented as available to every member with the server enforcing permission, matching React — the React Native role gate was removed in ENG-38197, so canPin() now only asserts that somebody is logged in. Verified: 0 dangling navigation refs, and 100 internal links across the changed files all resolve. --- docs.json | 4 +- ui-kit/react-native/core-features.mdx | 38 +++ .../guide-pin-and-save-messages.mdx | 230 ++++++++++++++++++ .../guide-thread-subscription.mdx | 164 +++++++++++++ .../react-native/threaded-messages-header.mdx | 41 ++++ 5 files changed, 476 insertions(+), 1 deletion(-) create mode 100644 ui-kit/react-native/guide-pin-and-save-messages.mdx create mode 100644 ui-kit/react-native/guide-thread-subscription.mdx diff --git a/docs.json b/docs.json index 035cebab9..ed0bcc943 100644 --- a/docs.json +++ b/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-thread-subscription", + "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/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index 639a389c6..7c052ef90 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -147,6 +147,31 @@ Mentions is a feature that enhances the interactivity and clarity of group or 1- | [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 & Save Messages + +Keep important messages in reach. Pinning highlights a message for **everyone** in the conversation; saving bookmarks it **privately** for the acting user, across all of their conversations. Both come with message options, bubble indicators, and dedicated full-screen views. + +| Components | Functionality | +| --- | --- | +| [MessageList](/ui-kit/react-native/message-list) | Provides the Pin/Unpin and Save/Unsave options and shows the bubble indicators. | +| [PinnedMessages](/ui-kit/react-native/pinned-messages) | Full-screen list of a conversation's pinned messages. | +| [SavedMessages](/ui-kit/react-native/saved-messages) | Full-screen, private list of the user's saved messages. | +| [MessageHeader](/ui-kit/react-native/message-header) | Built-in pinned-messages button, via `showPinnedMessagesButton`. | + +Pin and Save must be enabled for your app in the CometChat Dashboard. The UI Kit reads both at login and re-reads them on reconnection, so the options appear without any extra wiring. + +See the [Pin & Save Messages guide](/ui-kit/react-native/guide-pin-and-save-messages) for end-to-end wiring. + +## 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. + +| Components | Functionality | +| --- | --- | +| [Conversations](/ui-kit/react-native/conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. Hide it with `pinConversationOptionVisibility`. | + +Pin Conversations must be enabled for your app in the CometChat Dashboard. Ordering is server-owned — the list already arrives with pinned conversations first, so no client-side sorting is required. + ## 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 +261,19 @@ The Threaded Conversations feature enables users to respond directly to a specif | [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. Users are subscribed automatically when they send the parent message, reply in the thread, or are @mentioned in it — this feature lets them see and change that. + +| Components | Functionality | +| --- | --- | +| [MessageList](/ui-kit/react-native/message-list) | Provides the Subscribe to thread / Unsubscribe from thread option in the message options. Hide it with `hideThreadSubscriptionOption`. | +| [MessageHeader](/ui-kit/react-native/message-header) | Shows the subscription bell on the thread view, when given a `parentMessage`. Hide it with `threadSubscriptionVisibility`. | + +Enabled by default, and unlike Pin & Save it has no dashboard setting. To remove it app-wide, call `ThreadSubscriptionConfig.setEnabled(false)` during initialization. + +See the [Thread Subscription guide](/ui-kit/react-native/guide-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. diff --git a/ui-kit/react-native/guide-pin-and-save-messages.mdx b/ui-kit/react-native/guide-pin-and-save-messages.mdx new file mode 100644 index 000000000..c77c95418 --- /dev/null +++ b/ui-kit/react-native/guide-pin-and-save-messages.mdx @@ -0,0 +1,230 @@ +--- +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 Messages](/ui-kit/react-native/core-features#pin--save-messages). + + +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. + + +## 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"; + + +``` + +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. + + +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. + + +## 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"; + + + 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(); + const route = useRoute(); + const { user, group } = route.params ?? {}; + + return ( + + navigation.goBack()} + onItemPress={(message: CometChat.BaseMessage) => { + // Jump the main message list to this message. + navigation.navigate("Messages", { + user, + group, + messageId: String(message.getId()), + }); + }} + /> + + ); +}; + +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. + +| 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. | +| `hideUnpinMessageOption` | `boolean` | Hides the unpin option in the row's long-press menu. | + +## 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. + +_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(); + + return ( + + navigation.goBack()} + onItemPress={(message, source) => { + // `source` carries the conversation the message came from, so you can + // open that chat and jump to the message. + navigation.navigate("Messages", { + user: source?.user, + group: source?.group, + messageId: String(message.getId()), + }); + }} + /> + + ); +}; + +export default SavedMessages; +``` + +Each row shows which conversation the message came from, so a saved message is never orphaned from its context. + +| 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. | +| `hideUnsaveMessageOption` | `boolean` | Hides the unsave option in the row's long-press menu. | + +## 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 } from "@react-navigation/native"; +import { View } from "react-native"; + +const Messages = ({ user, group }: { user?: CometChat.User; group?: CometChat.Group }) => { + const navigation = useNavigation(); + + return ( + + + navigation.navigate("PinnedMessages", { user, group }) + } + /> + + + + + + + + ); +}; + +export default Messages; +``` + +## 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 diff --git a/ui-kit/react-native/guide-thread-subscription.mdx b/ui-kit/react-native/guide-thread-subscription.mdx new file mode 100644 index 000000000..5160b9f1a --- /dev/null +++ b/ui-kit/react-native/guide-thread-subscription.mdx @@ -0,0 +1,164 @@ +--- +title: "Thread Subscription" +sidebarTitle: "Thread Subscription" +description: "Let users subscribe to or unsubscribe from message threads so notifications only reach the people who care." +--- + +## Overview + +A busy group can generate a lot of thread replies. **Thread subscription** lets a user decide, per thread, whether its replies should notify them. + +Users are subscribed automatically when they take part — sending the parent message, replying in the thread, or being **@mentioned** in it all subscribe them. This feature gives them a way to see that state and change it. + +There are two surfaces, and they stay in sync: + +| Surface | Component | Control | +| --- | --- | --- | +| Message action sheet | `CometChatMessageList` | *Subscribe to thread* / *Unsubscribe from thread* | +| Thread header | `CometChatMessageHeader` | A bell that reflects the current state | + +## Prerequisites + +- Completed the [Integration Guide](/ui-kit/react-native/react-native-cli-integration) +- An existing chat screen using `CometChatMessageList`, and a thread screen using `CometChatMessageHeader` + +## Enable the Feature + +Thread subscription is **enabled by default** — there is nothing to switch on, and unlike Pin & Save it has no app setting in the dashboard. + +If you want to remove it, the UI Kit gives you three controls: + +_File: CometChatInitializer.ts_ + +```tsx +import { ThreadSubscriptionConfig } from "@cometchat/chat-uikit-react-native"; + +// App-wide kill switch. Both surfaces disappear. +ThreadSubscriptionConfig.setEnabled(false); +``` + + +`ThreadSubscriptionConfig` is a static, not React state — nothing re-renders when it changes. Call it once during initialization, before any chat UI mounts. + + +Or hide a single surface: + +```tsx +// Remove only the action-sheet option + + +// Remove only the thread-header bell + +``` + +The three controls combine with AND, and the global one wins: + +| `ThreadSubscriptionConfig` | Per-surface prop | Result | +| --- | --- | --- | +| `false` | anything | Neither surface renders | +| `true` | each prop | Each surface obeys its own prop independently | + +## Surface 1: The Message Action Sheet Option + +`CometChatMessageList` adds **Subscribe to thread** / **Unsubscribe from thread** to the message options automatically. The title reflects what a tap will *do*. + +_File: Messages.tsx_ + +```tsx +import { CometChatMessageList } from "@cometchat/chat-uikit-react-native"; + + +``` + +The option appears on a message **even before anyone has replied** — following a message ahead of the conversation is the point. It is not offered on a reply itself, only on the message that roots the thread. + +## Surface 2: The Thread Header Bell + +The bell lives on `CometChatMessageHeader`, and appears only when the header is given a `parentMessage`. That is what turns a conversation header into a *thread* header. + +_File: ThreadView.tsx_ + +```tsx +import { CometChat } from "@cometchat/chat-sdk-react-native"; +import { + CometChatMessageHeader, + CometChatMessageList, + CometChatThreadHeader, +} from "@cometchat/chat-uikit-react-native"; +import { Text, View } from "react-native"; + +const ThreadView = ({ + message, + user, + group, + onBack, +}: { + message: CometChat.BaseMessage; + user?: CometChat.User; + group?: CometChat.Group; + onBack: () => void; +}) => ( + + <>} + TitleView={() => Thread} + /> + + + + + + + +); + +export default ThreadView; +``` + + +Pass the whole `parentMessage` to `CometChatMessageList`, not just its ID. A reply arriving over the socket carries no subscription flag of its own, so the list stamps it from the thread's parent — the parent is the subscription authority. + + +The bell is **state-labelled**: it shows whether you *are* subscribed, rather than what a tap will do. That is the opposite convention to the action-sheet option, and it is deliberate — a header describes state, a menu item describes an action. + +### Hosting the Bell in Your Own Top Bar + +If you replace the header entirely, keep `parentMessage` on whatever `CometChatMessageHeader` you render, and use `TitleView` / `SubtitleView` / `LeadingView` to restyle it rather than dropping the component. Those slots let you keep the built-in bell and its state handling while owning the rest of the bar. + +## Behavior + +- **Subscribing is automatic on participation.** Sending the parent, replying, or being @mentioned subscribes the user. They do not have to find the control first. +- **Unsubscribing is not permanent.** Replying again, or being @mentioned again, re-subscribes them. The confirmation copy is worded to avoid promising otherwise. +- **The action is optimistic.** The control flips immediately, then reverts with a message if the server rejects it. +- **Repeated taps are guarded.** One request is in flight at a time per thread, and rapid taps are debounced. + +## Cross-Surface Sync + +The two surfaces share one source of truth. Toggling from the action sheet updates the bell, and toggling the bell updates the option — no refresh, no remount. + +## Notifications + +Subscription decides who is **notified** about new replies. It does not hide the thread, and it does not change who can read or reply. + + +Turning the feature off in the UI Kit hides the controls but does **not** stop subscriptions. Users are still subscribed automatically by replying or being @mentioned, and still receive thread notifications — they simply have no way to change it in the app. Suppressing the notifications themselves is a notification-settings concern, not a UI Kit one. + + +## Next Steps & Further Reading + +- [Thread Subscription (SDK)](/sdk/react-native/thread-subscription) — the underlying methods, listeners, and state +- [Threaded Messages](/ui-kit/react-native/guide-threaded-messages) — building the thread experience itself +- [CometChatThreadHeader](/ui-kit/react-native/threaded-messages-header) — the component reference diff --git a/ui-kit/react-native/threaded-messages-header.mdx b/ui-kit/react-native/threaded-messages-header.mdx index dbe4e5314..9888353b9 100644 --- a/ui-kit/react-native/threaded-messages-header.mdx +++ b/ui-kit/react-native/threaded-messages-header.mdx @@ -159,6 +159,47 @@ function CustomTemplateDemo() { --- +## Thread Subscription + +A thread view can show a **bell** that subscribes the user to the thread or unsubscribes them, so replies notify only the people who want them. The bell reflects the current state and toggles it on tap, updating optimistically and reverting with a message if the server rejects it. + + +On React Native the bell lives on **`CometChatMessageHeader`**, not on `CometChatThreadHeader`. The landed design places it in the thread screen's top bar rather than in the reply-count row, so give `CometChatMessageHeader` a `parentMessage` — that is what turns a conversation header into a thread header and renders the bell. + + +```tsx +import { + CometChatMessageHeader, + CometChatThreadHeader, +} from "@cometchat/chat-uikit-react-native"; + +// Top bar — owns the subscription bell + + +// Reply-count row — the parent message and its reply count + +``` + +To remove the bell, pass `threadSubscriptionVisibility={false}` to `CometChatMessageHeader`. The same subscribe/unsubscribe action is also offered as a message option in `CometChatMessageList`, controlled independently by `hideThreadSubscriptionOption` — an integrator may legitimately want one surface and not the other. + +Both surfaces are additionally gated by `ThreadSubscriptionConfig`, which is enabled by default. Setting it to `false` removes both, whatever the per-surface props say. + +| Control | Component | Scope | +| --- | --- | --- | +| `threadSubscriptionVisibility` | `CometChatMessageHeader` | This header only | +| `hideThreadSubscriptionOption` | `CometChatMessageList` | This list's message options | +| `ThreadSubscriptionConfig.setEnabled(false)` | — | App-wide; overrides both | + +`CometChatThreadHeader`'s own `TrailingView` replaces the trailing area of the reply-count bar. It is the escape hatch for putting your own control there — it does not host the subscription bell. + +See the [Thread Subscription guide](/ui-kit/react-native/guide-thread-subscription) for the full setup and behavior. + ## Next Steps From 984ef98ca16a03942039a059105d76715b534770 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 16:26:21 +0530 Subject: [PATCH 02/18] docs(react-native): match Android's Pin Conversations section verbatim The section had drifted from the Android original: different table headers (Components/Functionality vs Component/Role), a shortened link label, and two extra paragraphs about the dashboard flag and server-owned ordering. Now byte-identical to ui-kit/android/core-features.mdx, with only the platform path in the link differing. --- ui-kit/react-native/core-features.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index 7c052ef90..e31ab5134 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -166,11 +166,9 @@ See the [Pin & Save Messages guide](/ui-kit/react-native/guide-pin-and-save-mess 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. -| Components | Functionality | +| Component | Role | | --- | --- | -| [Conversations](/ui-kit/react-native/conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. Hide it with `pinConversationOptionVisibility`. | - -Pin Conversations must be enabled for your app in the CometChat Dashboard. Ordering is server-owned — the list already arrives with pinned conversations first, so no client-side sorting is required. +| [CometChatConversations](/ui-kit/react-native/conversations) | Provides the Pin/Unpin conversation option, the row indicator, and pinned-first ordering. | ## Rich Text Formatting From 3ca82161426068983c7077db1d1fb047e608a0b9 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 16:29:59 +0530 Subject: [PATCH 03/18] docs(react-native): match Android's core-features format for Pin & Save and Thread Subscription MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pin Conversations was aligned in 984ef98c; these two had drifted the same way — "Components/Functionality" table headers instead of "Component/Role", shortened link labels, and extra "Hide it with ..." clauses and paragraphs Android does not carry. Both now follow the Android sections verbatim. Three differences remain, each a real platform fact rather than drift: * Pin & Save — "Pinned messages entry point", not "menu entry point": on React Native it is a header button (showPinnedMessagesButton), not a menu item. * Thread Subscription — "Enabled by default" rather than Android's "Opt-in". React Native ships ThreadSubscriptionConfig with enabled = true. * Thread Subscription — the bell is on CometChatMessageHeader, not CometChatThreadHeader, per the landed React Native design. --- ui-kit/react-native/core-features.mdx | 24 ++++++++++-------------- 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index e31ab5134..3ce6b5ca4 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -149,16 +149,14 @@ Mentions is a feature that enhances the interactivity and clarity of group or 1- ## Pin & Save Messages -Keep important messages in reach. Pinning highlights a message for **everyone** in the conversation; saving bookmarks it **privately** for the acting user, across all of their conversations. Both come with message options, bubble indicators, and dedicated full-screen views. +Keep important messages in reach. Pinning highlights a message for **everyone** in the conversation; saving bookmarks it **privately** for the acting user, across all of their conversations. Both come with action-sheet options, bubble indicators, and dedicated full-screen views. -| Components | Functionality | +| Component | Role | | --- | --- | -| [MessageList](/ui-kit/react-native/message-list) | Provides the Pin/Unpin and Save/Unsave options and shows the bubble indicators. | -| [PinnedMessages](/ui-kit/react-native/pinned-messages) | Full-screen list of a conversation's pinned messages. | -| [SavedMessages](/ui-kit/react-native/saved-messages) | Full-screen, private list of the user's saved messages. | -| [MessageHeader](/ui-kit/react-native/message-header) | Built-in pinned-messages button, via `showPinnedMessagesButton`. | - -Pin and Save must be enabled for your app in the CometChat Dashboard. The UI Kit reads both at login and re-reads them on reconnection, so the options appear without any extra wiring. +| [CometChatMessageList](/ui-kit/react-native/message-list) | Provides the Pin/Unpin and Save/Unsave options and shows the bubble footer indicators. | +| [CometChatPinnedMessages](/ui-kit/react-native/pinned-messages) | Full-screen list of a conversation's pinned messages. | +| [CometChatSavedMessages](/ui-kit/react-native/saved-messages) | Full-screen, private list of the user's saved messages. | +| [CometChatMessageHeader](/ui-kit/react-native/message-header) | Built-in "Pinned messages" entry point. | See the [Pin & Save Messages guide](/ui-kit/react-native/guide-pin-and-save-messages) for end-to-end wiring. @@ -261,14 +259,12 @@ The Threaded Conversations feature enables users to respond directly to a specif ## Thread Subscription -Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Users are subscribed automatically when they send the parent message, reply in the thread, or are @mentioned in it — this feature lets them see and change that. +Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Enabled by default — remove it with `ThreadSubscriptionConfig.setEnabled(false)`. -| Components | Functionality | +| Component | Role | | --- | --- | -| [MessageList](/ui-kit/react-native/message-list) | Provides the Subscribe to thread / Unsubscribe from thread option in the message options. Hide it with `hideThreadSubscriptionOption`. | -| [MessageHeader](/ui-kit/react-native/message-header) | Shows the subscription bell on the thread view, when given a `parentMessage`. Hide it with `threadSubscriptionVisibility`. | - -Enabled by default, and unlike Pin & Save it has no dashboard setting. To remove it app-wide, call `ThreadSubscriptionConfig.setEnabled(false)` during initialization. +| [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-thread-subscription) for setup and behavior. From ea96d91dc58979e2839e81c22e0378a3d5b70f46 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 16:45:35 +0530 Subject: [PATCH 04/18] docs(react-native): drop hideUnpinMessageOption from the CometChatPinnedMessages prop table --- ui-kit/react-native/guide-pin-and-save-messages.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/ui-kit/react-native/guide-pin-and-save-messages.mdx b/ui-kit/react-native/guide-pin-and-save-messages.mdx index c77c95418..54587073b 100644 --- a/ui-kit/react-native/guide-pin-and-save-messages.mdx +++ b/ui-kit/react-native/guide-pin-and-save-messages.mdx @@ -116,7 +116,6 @@ export default PinnedMessages; | `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. | -| `hideUnpinMessageOption` | `boolean` | Hides the unpin option in the row's long-press menu. | ## Step 3: Add a "Saved" Screen From 30ab6f8d5ff6f8899ae3fdb345352f1e86163212 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 16:48:41 +0530 Subject: [PATCH 05/18] docs(react-native): drop hideUnsaveMessageOption from the CometChatSavedMessages prop table --- ui-kit/react-native/guide-pin-and-save-messages.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/ui-kit/react-native/guide-pin-and-save-messages.mdx b/ui-kit/react-native/guide-pin-and-save-messages.mdx index 54587073b..281d2383d 100644 --- a/ui-kit/react-native/guide-pin-and-save-messages.mdx +++ b/ui-kit/react-native/guide-pin-and-save-messages.mdx @@ -160,7 +160,6 @@ Each row shows which conversation the message came from, so a saved message is n | `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. | -| `hideUnsaveMessageOption` | `boolean` | Hides the unsave option in the row's long-press menu. | ## Step 4: Pinned & Saved Indicators From bf75dc1254471b5e41fdaadbc0099be5954e68b4 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 17:08:17 +0530 Subject: [PATCH 06/18] docs(react-native): drop every ThreadSubscriptionConfig reference Removes all 12 mentions across four pages. Thread subscription is now documented purely through its two per-surface props: hideThreadSubscriptionOption CometChatMessageList threadSubscriptionVisibility CometChatMessageHeader message-list.mdx dropped the opt-out paragraph, the TypeScript/JavaScript tabs that only demonstrated setEnabled, and the mention in the hideThreadSubscriptionOption prop description guide-thread-subscription "Enable the Feature" rewritten around the two props threaded-messages-header dropped the global row from the controls table core-features points at the two props instead The feature is still described as enabled by default, which is what 5.5.0 ships. --- ui-kit/react-native/core-features.mdx | 2 +- .../guide-thread-subscription.mdx | 31 +++++-------------- ui-kit/react-native/message-list.mdx | 29 ++--------------- .../react-native/threaded-messages-header.mdx | 3 -- 4 files changed, 12 insertions(+), 53 deletions(-) diff --git a/ui-kit/react-native/core-features.mdx b/ui-kit/react-native/core-features.mdx index 3ce6b5ca4..22dab9b03 100644 --- a/ui-kit/react-native/core-features.mdx +++ b/ui-kit/react-native/core-features.mdx @@ -259,7 +259,7 @@ The Threaded Conversations feature enables users to respond directly to a specif ## Thread Subscription -Let users subscribe to or unsubscribe from a thread to control whether its replies notify them. Enabled by default — remove it with `ThreadSubscriptionConfig.setEnabled(false)`. +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 | | --- | --- | diff --git a/ui-kit/react-native/guide-thread-subscription.mdx b/ui-kit/react-native/guide-thread-subscription.mdx index 5160b9f1a..e907e6156 100644 --- a/ui-kit/react-native/guide-thread-subscription.mdx +++ b/ui-kit/react-native/guide-thread-subscription.mdx @@ -26,37 +26,22 @@ There are two surfaces, and they stay in sync: Thread subscription is **enabled by default** — there is nothing to switch on, and unlike Pin & Save it has no app setting in the dashboard. -If you want to remove it, the UI Kit gives you three controls: - -_File: CometChatInitializer.ts_ +Each surface has its own prop, so you can remove one without the other: ```tsx -import { ThreadSubscriptionConfig } from "@cometchat/chat-uikit-react-native"; - -// App-wide kill switch. Both surfaces disappear. -ThreadSubscriptionConfig.setEnabled(false); -``` - - -`ThreadSubscriptionConfig` is a static, not React state — nothing re-renders when it changes. Call it once during initialization, before any chat UI mounts. - - -Or hide a single surface: - -```tsx -// Remove only the action-sheet option +// Remove the action-sheet option -// Remove only the thread-header bell +// Remove the thread-header bell ``` -The three controls combine with AND, and the global one wins: - -| `ThreadSubscriptionConfig` | Per-surface prop | Result | +| Prop | Component | Removes | | --- | --- | --- | -| `false` | anything | Neither surface renders | -| `true` | each prop | Each surface obeys its own prop independently | +| `hideThreadSubscriptionOption` | `CometChatMessageList` | The Subscribe / Unsubscribe message option | +| `threadSubscriptionVisibility` | `CometChatMessageHeader` | The bell on the thread view | + +Pass both to remove the feature from your app entirely. ## Surface 1: The Message Action Sheet Option diff --git a/ui-kit/react-native/message-list.mdx b/ui-kit/react-native/message-list.mdx index 57db017ba..d5f524522 100644 --- a/ui-kit/react-native/message-list.mdx +++ b/ui-kit/react-native/message-list.mdx @@ -448,33 +448,10 @@ These actions appear in the message options sheet, each with a prop to hide it. every reconnect, so an option renders only when the Dashboard allows it *and* the prop does not hide it. There is no start-up call to make. - Thread subscription is different: it is not an app setting, so `ThreadSubscriptionConfig` is a real - switch — and it defaults to **on**, matching the React UI Kit. The option shows unless you opt out. + Thread subscription is different: it is not an app setting. The option shows by default, matching + the React UI Kit, so `hideThreadSubscriptionOption` is how you remove it. - - -```typescript -import { ThreadSubscriptionConfig } from "@cometchat/chat-uikit-react-native"; - -// Thread subscription is on by default — call this only to opt OUT. -// Pin and Save need no equivalent: the kit reads their Dashboard flags at login. -ThreadSubscriptionConfig.setEnabled(false); -``` - - - - -```javascript -import { ThreadSubscriptionConfig } from "@cometchat/chat-uikit-react-native"; - -ThreadSubscriptionConfig.setEnabled(false); -``` - - - - - The Dashboard flag and the per-instance prop are **ANDed**: the Dashboard decides whether a feature is available to your app at all, and these props hide it on one particular list. @@ -1197,7 +1174,7 @@ Hides suggested messages in AI view. ### hideThreadSubscriptionOption -Hides the "Follow / Unfollow thread" option. Unlike pin and save, `ThreadSubscriptionConfig` defaults to **on**, so this prop is the usual way to hide it. +Hides the "Follow / Unfollow thread" option. Unlike pin and save, it is not gated on a Dashboard setting — the option shows by default, so this prop is how you hide it. | | | | --- | --- | diff --git a/ui-kit/react-native/threaded-messages-header.mdx b/ui-kit/react-native/threaded-messages-header.mdx index 9888353b9..3ea948f12 100644 --- a/ui-kit/react-native/threaded-messages-header.mdx +++ b/ui-kit/react-native/threaded-messages-header.mdx @@ -188,13 +188,10 @@ import { To remove the bell, pass `threadSubscriptionVisibility={false}` to `CometChatMessageHeader`. The same subscribe/unsubscribe action is also offered as a message option in `CometChatMessageList`, controlled independently by `hideThreadSubscriptionOption` — an integrator may legitimately want one surface and not the other. -Both surfaces are additionally gated by `ThreadSubscriptionConfig`, which is enabled by default. Setting it to `false` removes both, whatever the per-surface props say. - | Control | Component | Scope | | --- | --- | --- | | `threadSubscriptionVisibility` | `CometChatMessageHeader` | This header only | | `hideThreadSubscriptionOption` | `CometChatMessageList` | This list's message options | -| `ThreadSubscriptionConfig.setEnabled(false)` | — | App-wide; overrides both | `CometChatThreadHeader`'s own `TrailingView` replaces the trailing area of the reply-count bar. It is the escape hatch for putting your own control there — it does not host the subscription bell. From 1f1c31d77af417749f1770db97a5b54ab63fcaa5 Mon Sep 17 00:00:00 2001 From: Suraj Chauhan Date: Thu, 10 Sep 2026 17:16:49 +0530 Subject: [PATCH 07/18] docs(react-native): core-features Pin and Save now follows React, not Android MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The five bullets specify per-section references, and Pin & Save in core features is a React one — it had been switched to Android's format along with the other two sections. Now follows ui-kit/react/core-features.mdx: React's heading ("Pin and Save Messages"), intro, Components/Functionality table, and — the part Android's version does not carry — the app-settings limits table and its closing paragraph on cap toasts. Five deliberate differences: * the Storybook +