From 828f4ae3a96467f299a4ecb49e58dca36bd1e87e Mon Sep 17 00:00:00 2001 From: HADES248 Date: Mon, 4 Aug 2025 17:28:13 +0530 Subject: [PATCH] Add threaded messages guide to documentation --- docs.json | 1 + ui-kit/react/threaded-messages-guide.mdx | 108 +++++++++++++++++++++++ 2 files changed, 109 insertions(+) create mode 100644 ui-kit/react/threaded-messages-guide.mdx diff --git a/docs.json b/docs.json index 6b3c8681..a3d9a9d7 100644 --- a/docs.json +++ b/docs.json @@ -401,6 +401,7 @@ { "group": "Guides", "pages": [ + "ui-kit/react/threaded-messages-guide", "ui-kit/react/custom-text-formatter-guide", "ui-kit/react/mentions-formatter-guide", "ui-kit/react/url-formatter-guide", diff --git a/ui-kit/react/threaded-messages-guide.mdx b/ui-kit/react/threaded-messages-guide.mdx new file mode 100644 index 00000000..4bcb4889 --- /dev/null +++ b/ui-kit/react/threaded-messages-guide.mdx @@ -0,0 +1,108 @@ +--- +title: Threaded Messages +--- +## Overview +The sample app demonstrates how to enable threaded messaging in React using CometChat’s UI Kit: +* **What:** CometChatThreadedMessages renders a thread view for a single parent message—showing the original message, its replies, and a composer. +* **Why:** Threaded conversations keep context intact in busy chats by isolating sub-conversations under a specific message. +* **Result:** Users can view and send replies in-context, close the thread, and—if blocked—see an unblock prompt. +## Prerequisites +* React 17+ or 18+ project +* @cometchat/chat-sdk-javascript and @cometchat/react-ui-kit installed +* Valid CometChat initialization (appID, region, authKey) done at app root +* Access to useCometChatContext() for feature flags +## Components +| Component | Role | +| ------------------------------ | ------------------------------------------------------------- | +| `CometChatThreadedMessages` | Parent component rendering header, list, composer, etc | +| `CometChatThreadHeader` | Displays the original (parent) message and close button | +| `CometChatMessageList` | Shows threaded replies; accepts parentMessageId | +| `CometChatMessageComposer` | Input UI to send thread replies; uses parentMessageId | +## Integration Steps +### Install & Import Dependencies +**Goal:** Add required packages and imports. +```bash +npm install @cometchat/chat-sdk-javascript @cometchat/react-ui-kit +``` +**Why:** Provides thread UI components and SDK methods. +### Fetch Parent Message & Build Request +**Goal:** Retrieve the parent message and prepare a MessagesRequestBuilder. +```typescript +message: CometChat.BaseMessage; +requestBuilderState?: CometChat.MessagesRequestBuilder; +... +messagesRequestBuilder={requestBuilderState} +``` +**File reference:**\ +[`ThreadedMessages.tsx`](https://github.com/cometchat/cometchat-uikit-react/blob/v6/sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx) +**Why:** Needed to pass the parent message and request builder into the threaded component. +### Render the UI +**Goal:** Display the full thread UI. +```tsx +
+ +
+
+ +
+
+ +
+``` +**File reference:**\ +[`ThreadedMessages.tsx`](https://github.com/cometchat/cometchat-uikit-react/blob/v6/sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx) +**Why:** Provides a focused UI for thread interactions. +### Send a Threaded Message +**Goal:** Send replies in the context of a thread. +```tsx + +``` +**File reference:**\ +[`ThreadedMessages.tsx`](https://github.com/cometchat/cometchat-uikit-react/blob/v6/sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx) +**Why:** Automatically associates new messages with the parent thread. +### Fetch & Display Thread Replies +**Goal:** Retrieve and show all replies under a parent message. +```tsx + +``` +**File reference:**\ +[`ThreadedMessages.tsx`](https://github.com/cometchat/cometchat-uikit-react/blob/v6/sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx) +**Why:** Ensures only relevant threaded messages are shown. +## Customization Options +Hide Receipts / Reactions: +```typescript +hideReceipts={!chatFeatures.coreMessagingExperience.messageDeliveryAndReadReceipts} +hideReactions={!chatFeatures.deeperUserEngagement.reactions} +``` +**Custom Composer Props:** Pass additional props to CometChatMessageComposer for voice notes, polls, etc. +**Styling Overrides:** Use CSS-in-JS or override kit’s class names to match your theme. +## Filtering / Edge Cases +* **Parent Deleted:** Show a fallback message or disable composer if parent is deleted. +* **No Replies:** Display an empty state (e.g., “No replies yet”). +* **Offline Mode:** Queue thread operations or show connectivity indicators. +## Error Handling & Edge Cases +* **Fetch Failures:** Show error UI with retry option on `fetchPrevious` errors. +* **Send Failures:** Display SnackBar on composer send errors; allow retry. +* **Loading States:** Show loading indicators during fetch/send operations. +## Optional Context-Specific Notes +* **SDK Errors:** Wrap getMessage and fetch calls in .catch() and display an error banner. +* **Blocked Users:** Use showComposer=false to trigger unblock UI; handle ccUserUnblocked event from CometChatUserEvents +## Summary / Feature Matrix +| Feature | Component / Method | +| ------------------------- | ----------------------------------------------- | +| Parent message header + close button | `message={parentMessage} + onClose={handleThreadClose}` | +| Display threaded replies | `messagesRequestBuilder={requestBuilder}` | +| Send replies in thread | `showComposer={true}` | +| Hide UI per feature flags | `hideReactions, hideReceipts, etc.` | +| Blocked-user UI | `showComposer={false} triggers unblock block` | +## Next Steps & Further Reading +* **Full Sample App:**\ + [https://github.com/cometchat/cometchat-uikit-react](https://github.com/cometchat/cometchat-uikit-react) \ No newline at end of file