docs(react,sdk/javascript): align thread subscription and pin/save with other platforms

[PrajwalDhuleCC]

Description

Bring the React UI Kit and JavaScript SDK docs onto the same page as Android, Angular and iOS for thread subscription, pin & save, and pin conversations.

React UI Kit:

• core-features: add Thread Subscription as a subsection of Threaded Conversations, which previously carried no mention of the feature. Unlike Android and Angular, React has no enable flag, so the section says so explicitly rather than inheriting their "off by default" framing.
• core-features: split Pin Conversations into its own section instead of bundling it as a row of the Pin & Save table, matching Android.
• core-features and the pin/save guide: pair the .enabled keys with the .limit keys, so each section documents both halves of its app settings.
• core-features: add Message Bubble and Message Header to the Pin & Save component table; both behaviours were already documented in the guide but missing from the table.
• Retitle the guide's Limits step to App Settings and Limits, and repoint the conversation-pin links at the Pin Conversation anchor.

JavaScript SDK:

• thread-subscription: add Notification Preferences, covering RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS, and cross-link the QuotedRepliesOptions content in notifications/preferences. Flag that the two enums are distinct so the raw value 4 is not read as interchangeable.
• pin-message, save-message, pin-conversation: add Error Handling. Only ERR_ACTION_NOT_ALLOWED was named anywhere across these pages, leaving nothing to branch on in a catch block; the limit-exceeded codes were invisible despite the Pin Limit section advising callers to pre-empt the cap. Codes are read off the kit's own handling, and the sections point at the limit getters as the source for the cap rather than the error text.

Custom text formatter guide:

• Rewrites ui-kit/react/guide-custom-text-formatter.mdx into one end-to-end flow — token and display, serialize on send, color as you type, color a selection, the toolbar button, wiring it into the composer, and registering it on every surface — replacing the previous partial example. It is in this PR because the same pass covered the React formatter surface; happy to split it out if you'd rather review it separately.
• Every step heading is renamed. There are no inbound links to the old anchors, in this repo or the nav, so nothing breaks.
• The marker is {color:#hex}…{/color}, matching the React Native guide in feat(react-native-uikit-docs): Pin & Save, Pin Conversation and Thread Subscription #536 (merged) so one token renders on both platforms.
• The complete code compiles against @cometchat/chat-uikit-react 7.2.x and was run end-to-end: a stored token renders as a colored span on the message list, and the composer round-trips it back to the token on send.

System pin limit keys are deliberately left out of the UI Kit docs: the kit reads isSystemPinned() for ordering and for suppressing unpin, never the features.ux.*.system.limit settings, and a user cannot system-pin from the UI. They stay documented on the SDK side, where they are reachable.

Docs only; no UI Kit or SDK source changes.

Related Issue(s)

Type of Change

• Documentation correction/update
• New documentation
• Improvement to existing documentation
• Typo fix
• Other (please specify)

Checklist

• I have read the CONTRIBUTING document
• My branch name follows the naming convention
• My changes follow the documentation style guide
• I have checked for spelling and grammar errors
• All links in my changes are valid and working
• My changes are accurately described in this pull request

Additional Information

Screenshots (if applicable)

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
cometchat	🟢 Ready	View Preview	Sep 29, 2026, 2:59 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[raj-dubey1]

Review: changes requested on the SDK error-handling tables

The structure is clean and the React UI Kit half is accurate. The new Error Handling tables in the JS SDK pages are there so readers can branch on codes, but several rows give the wrong meaning, and pin-message.mdx now contradicts itself. I checked each code against the chat-api server source (master, 2026-09-01), JS SDK 4.2.0, and React UI Kit 7.2.0.

Must fix

1. sdk/javascript/pin-message.mdx gives two different codes for a member's pin

• The intro note at L9-11 says a member's pin is rejected with ERR_ACTION_NOT_ALLOWED.
• The new table at L248-249 says role refusal is ERR_PERMISSION_DENIED.
• The server returns ERR_PERMISSION_DENIED for a role/scope refusal, so the table is right and the intro is stale. Please update L9-11 in this PR so the page says one thing. (The SDK's own JSDoc for pinMessage has the same stale ERR_ACTION_NOT_ALLOWED claim, which is probably where it came from.)

2. "ERR_ACTION_NOT_ALLOWED = feature not enabled" is wrong in all three tables (pin-message.mdx L249, pin-conversation.mdx L243, save-message.mdx L256)

• When the feature is off, the pin, unpin, save, unsave and conversation pin/unpin endpoints return ERR_FEATURE_NOT_ACCESSIBLE (HTTP 403, "…feature is not available. To enable this feature, please upgrade your plan.").
• The server never returns ERR_ACTION_NOT_ALLOWED for these calls. The SDK declares it as a constant but never throws it, so a catch block built from this table will never catch the feature-off case.
• The kit doesn't give the two codes separate meanings: it treats ERR_ACTION_NOT_ALLOWED and ERR_PERMISSION_DENIED as one "permission" group. If you keep ERR_ACTION_NOT_ALLOWED, describe it as a permission refusal next to ERR_PERMISSION_DENIED, not as feature-off.

3. sdk/javascript/pin-conversation.mdx lists a code this endpoint can't return, and misses the real one

• L244 ERR_PERMISSION_DENIED: conversation pin/unpin has no role or permission check, so this endpoint never returns it.
• Pinning or unpinning a system-pinned conversation returns ERR_SYSTEM_PINNED_CONVERSATION. L246 mentions system pins without naming the code, and the older L87 says it's ERR_ACTION_NOT_ALLOWED. Please name ERR_SYSTEM_PINNED_CONVERSATION in the table and fix L87.

Nits

4. "The code arrives either top-level or nested, so read it defensively" (pin-message.mdx L253, pin-conversation.mdx L248, save-message.mdx L261). This isn't true for the SDK: every pin/save rejection is wrapped in a CometChatException, so error.code is always top-level, as the sentence above it says. The (error as any)?.error?.code pattern comes from the kit's internal helper. It's also TypeScript-only, while the rest of these pages use TS/JS <Tabs>. Plain error.code in Tabs would match the existing Error Handling section in thread-subscription.mdx.
5. The code lists are incomplete. The server also returns:
   • ERR_MESSAGE_ID_NOT_FOUND for a deleted or unknown message.
   • ERR_MESSAGE_ACTION_NOT_ALLOWED when pinning a message that moderation rejected (ERR_MESSAGE_NO_ACCESS covers only pending moderation and non-participants).
   • ERR_CONVERSATION_NOT_FOUND for conversation pin/unpin.
6. save-message.mdx L259: "a user may always save any message they can see" contradicts the row above it. A sender can see their own pending-moderation message, but saving it fails with ERR_MESSAGE_NO_ACCESS, and the save cap also applies. Something like "no role gate: any participant can save a message they have access to, up to the cap."
7. The limit notes (pin-message.mdx L260, pin-conversation.mdx L255, save-message.mdx L268) say the getter "returns the configured value directly". The getters return Promise<number | null>, so "resolves to the configured cap, or null when unset" matches the section right above.
8. thread-subscription.mdx L322: the snippet builds GroupPreferences but never calls setGroupPreferences() or CometChatNotifications.updatePreferences(), so copying it changes nothing. It also covers groups only, though threads work in 1:1 too (OneOnOnePreferences.setRepliesPreference exists). It's a single TS block, while the rest of the page uses TS/JS Tabs.
9. ui-kit/react/core-features.mdx L172: "The UI Kit also subscribes a user automatically…". The server does the auto-subscribe (it covers the replier, mentioned members, and the thread starter unless they unfollowed), so SDK-only apps get it too. The wording comes from the existing threaded-messages guide, so fixing both is optional.
10. ui-kit/react/core-features.mdx L214: "a cap on how many items a user may pin" doesn't hold for pinned messages, which are capped per conversation (the row right below says so).

What checked out

• Structure: no files moved or deleted, so no redirects are needed. There are 0 broken docs.json page references, so the build is safe.
• Links: 0 broken internal links in the changed files. All 28 #anchor links resolve, including the renamed #step-5-app-settings-and-limits, and nothing still links to the old #step-5-limits.
• "No enable flag" for React thread subscription is correct. The kit has only the hide* props and useThreadSubscription, and the server has no flag.
• The "raw 4" warning is correct. At runtime RepliesOptions.SUBSCRIBE_TO_SUBSCRIBED_THREADS and QuotedRepliesOptions.SUBSCRIBE_TO_QUOTES_ON_OWN_MESSAGES are both 4, and this matches notifications/preferences.mdx.
• The new React rows are accurate: the Message Header "Pinned messages" entry, the features.ux.*.enabled / .limit keys, and the limit getter signatures.

Already broken on main, not from this PR: /sdk/javascript/default-call and /sdk/javascript/direct-call (in message-structure-and-hierarchy.mdx), and /sdk/javascript/interactive-messages (in send-message.mdx).

These codes come from reading the server source, not from live calls. A quick live check of the feature-off and system-pin cases would be worth doing if the deployed server differs.

[raj-dubey1]

Review: request changes (small fixes)

The PR is safe to build and breaks no URLs: it removes and renames nothing, has no dangling navigation entries, and every link it adds resolves, including the #anchors. I checked the SDK claims against the real packages (JS SDK 4.2.0, React UI Kit 7.2.2), and they hold: the enum values, the namespaced notification classes and setters, and the limit getters all exist.

Three things should be fixed before merge.

P1: fix before merge

1. A TypeScript example won't compile (sdk/javascript/pin-conversation.mdx, new Error Handling tab, around line 254).
   • It uses (response: CometChat.BaseMessage) => …, but pinConversation() resolves with a Conversation. The SDK declares it as Promise<Conversation>, and the same page says so at lines 22 and 45.
   • With strict function types this is a type error.
   • Fix: (conversation: CometChat.Conversation) => ….
2. Unrelated rewrite bundled in (ui-kit/react/guide-custom-text-formatter.mdx, +973/−85, commit 960f12a).
   • The PR description covers thread subscription and pin/save only; this rewrite isn't mentioned.
   • It renames every step heading. I found no inbound links to the old anchors, so nothing breaks.
   • Please split it into its own PR, or at least describe it in this one.
3. The new guide contradicts ui-kit/react/plugins/text-formatters.mdx.
   • The guide links that page as "the full CometChatTextFormatter API".
   • The reference shows getRegex() and format() as abstract ("Must store originalText…"). It doesn't mention customLogicToFormatText, getOriginalText, onKeyUp, formatText, initializeComposerTracking, inputElementReference, the caret helpers or reRender.
   • The guide says you don't need to override format(), and its complete class implements neither method.
   • I checked the published 7.2.2 declarations: the guide is right. Only id is abstract, and format() delegates to customLogicToFormatText.
   • Please update the reference page's class sketch in this PR. Otherwise readers who follow the link will conclude the guide's code is broken.

P2 / nits

• Pin-message error code now differs between SDKs. sdk/javascript/pin-message.mdx changes the code to ERR_PERMISSION_DENIED, which matches iOS and Android. sdk/react-native/pin-message.mdx:38 still says ERR_ACTION_NOT_ALLOWED.
• New error codes missing from the JS error-codes page. ERR_PINNED_*_LIMIT_EXCEEDED, ERR_SAVED_MESSAGES_LIMIT_EXCEEDED, ERR_MESSAGE_NO_ACCESS and ERR_SYSTEM_PINNED_CONVERSATION are listed in articles/error-guide.mdx but not in sdk/javascript/error-codes.mdx.
• One link wasn't repointed. ui-kit/react/event-system.mdx:141 still sends "Pin a conversation" to conversations#hidepinconversation; everything else now points to #pin-conversation.
• Linked page has broken snippets (pre-existing). thread-subscription.mdx now links /notifications/preferences, whose snippets use bare new NotificationPreferences(). That's undefined at runtime in SDK 4.2.0; the working class is CometChatNotifications.NotificationPreferences. This PR's own snippets are correct. Worth a follow-up.
• Style. The new pin-conversation snippet uses the literal "user" where the rest of the page uses CometChat.RECEIVER_TYPE.USER. The formatter guide's #[0-9a-fA-F]{3,6} also accepts 5-digit hex, which isn't a valid CSS colour.

What passed

• Redirects: 0 removed or renamed pages, so there's nothing to redirect.
• Navigation: 0 unresolved pages entries.
• Links: 0 broken links in the changed pages. There are 3 broken links in unchanged SDK pages (message-structure-and-hierarchy → direct-call / default-call, and send-message → interactive-messages), outside this PR's scope.
• Anchors: every new #anchor resolves, and the #step-5-limits rename is repointed everywhere.
• Enum warning: the "raw value 4" warning is accurate. RepliesOptions 4 is SUBSCRIBE_TO_SUBSCRIBED_THREADS; QuotedRepliesOptions 4 is SUBSCRIBE_TO_QUOTES_ON_OWN_MESSAGES.
• Formatter priorities (10 / 20 / 100) match the reference.
• No placeholders, stale version pins or missing images in the changed pages.

[PrajwalDhuleCC]

@raj-dubey1

P1

P1.1 - fixed

P1.2 - updated the PR description

P1.3 - the text-formatters reference contradicting the guide — is resolved by merging main, which carries the corrected class sketch. fixed

P2

P2.3 - updated the link

P2.3 - updated to use CometChat.RECEIVER_TYPE.USER

rest of the Nits don't seem worth addressing in this PR