diff --git a/REACT_V7_UIKIT_DASHBOARD_STITCHING_AUDIT.md b/REACT_V7_UIKIT_DASHBOARD_STITCHING_AUDIT.md new file mode 100644 index 000000000..881787f6d --- /dev/null +++ b/REACT_V7_UIKIT_DASHBOARD_STITCHING_AUDIT.md @@ -0,0 +1,165 @@ +# React v7 UI Kit — Dashboard-Enablement & Stitching Audit + +**Scope:** `ui-kit/react` (v7 only — the default version). Audits every feature/component whose doc describes something that (a) must be **enabled in the CometChat Dashboard**, or (b) requires **manual "stitching"** (developer wiring: event handlers, connecting components, required props, navigation callbacks, SDK setup). For each, it records whether the page already links to a feature guide / "how it works" reference, and **what link/reference should be added and where**. + +**Legend — Type** +- `Dashboard` — a Dashboard extension / AI feature / add-on / setting must be turned on for this to work. +- `Stitch` — developer code required (handlers, required entity props, connecting components, SDK calls). +- `Both` — needs Dashboard enablement **and** wiring. + +**Reference status** +- `Yes` = links to the right guide · `Partial` = inline example or component card only, no guide link · `No` = points to nothing. + +--- + +## Part 1 — Dashboard-enablement required + +These render/behave only when a Dashboard extension, AI feature, add-on, or app setting is enabled. Most auto-integrate in code, so the docs should say *"enable X in the Dashboard"* and link the feature guide. + +| # | Page | Feature | Type | What must be enabled | Ref | Recommended link to add | +|---|------|---------|------|----------------------|-----|-------------------------| +| 1 | `components/message-composer` | Attachment options: **Polls, Collaborative Document, Collaborative Whiteboard, Stickers** (`hideAttachmentOptions`, `hideStickersButton`) | Dashboard | Each extension enabled in Dashboard; composer auto-integrates | No | Link Attachments / `hideAttachmentOptions` / `hideStickersButton` → `/ui-kit/react/extensions` (+ specific extension guides) | +| 2 | `components/message-list` | **Translate** message option (`hideTranslateMessageOption`) | Dashboard | Message Translation extension | No | Link Translate option → `/ui-kit/react/extensions` / `/fundamentals/message-translation` | +| 3 | `components/message-list` | **Flag / Report & Moderation view** (`hideFlagMessageOption`, `hideModerationView`, `hideFlagRemarkField`) | Dashboard | Moderation rules / Report Message configured in Dashboard | No | Link moderation props → `/moderation/overview` | +| 4 | `components/message-composer` | Attachment **count/size/type limits** (`file.count.max`, `file.size.max`, RBAC/SBAC file-type perms) | Dashboard | App settings & role-based file-type permissions in Dashboard | No | Link "Attachment limits / Why a file is rejected" → app-settings / RBAC-SBAC dashboard doc | +| 5 | `components/poll-bubble` | **Poll Bubble** (renders `extension_poll`) | Both | Polls extension (composer sends polls; `onVoteSubmit`/`onVoteError` wiring) | Partial → `plugins/overview` | Add `/fundamentals/polls` + note "Polls extension must be enabled in Dashboard" | +| 6 | `components/sticker-bubble` | **Sticker Bubble** (renders `extension_sticker`) | Dashboard | Stickers extension + sticker sets configured | Partial → `plugins/overview` | Add `/fundamentals/stickers` + Dashboard-enable note | +| 7 | `components/collaborative-document-bubble` | **Collaborative Document Bubble** (`@injected.extensions.document.document_url`) | Both | Collaborative Document extension; optional `onButtonClick` | Partial → `plugins/overview` | Add `/fundamentals/collaborative-document` + Dashboard-enable note | +| 8 | `components/collaborative-whiteboard-bubble` | **Collaborative Whiteboard Bubble** (`@injected.extensions.whiteboard.board_url`) | Both | Collaborative Whiteboard extension; optional `onButtonClick` | Partial → `plugins/overview` | Add `/fundamentals/collaborative-whiteboard` + Dashboard-enable note | +| 9 | `components/video-bubble` | **Auto poster thumbnails** (`thumbnail-generation` extension) | Dashboard | Thumbnail Generation extension (falls back to first frame) | No (named, not linked) | Link `thumbnail-generation` → `/fundamentals/thumbnail-generation` | +| 10 | `components/flag-message-dialog` | **Report reasons** via `CometChat.getFlagReasons()` | Both | Report Message / Moderation config (custom reasons) in Dashboard; parent implements `onSubmit` | No | Add `/moderation/overview` near "Reason Fetching" (no Next Steps section exists) | +| 11 | `components/message-header` | **Conversation Summary** button (`showConversationSummaryButton`, `enableAutoSummaryGeneration`, `onSummaryClick`) | Both | Conversation Summary AI feature; also requires wiring (see Part 2 #15) | No | Link summary props → `/ui-kit/react/ai-features` + `/fundamentals/ai-user-copilot/overview` | +| 12 | `components/message-list` | **Smart Replies** (`showSmartReplies`, defaults `false`) | Both | Smart Replies AI feature | No | Link → `/ui-kit/react/ai-features` | +| 13 | `components/message-list` | **Conversation Starters** (`showConversationStarters`, defaults `false`) | Both | Conversation Starter AI feature | No | Link → `/ui-kit/react/ai-features` | +| 14 | `components/message-composer` | **AI button** (`hideAIButton` defaults `true`) | Both | AI features enabled; dev must opt in | No | Link `hideAIButton`/`AIButton` → `/ui-kit/react/ai-features` | +| 15 | `components/ai-assistant-chat` | **AI Assistant Chat** (`user` prop = AI agent entity) | Both | **AI Agent configured in Dashboard** as a `CometChat.User`; metadata (`suggestedMessages`, `greetingMessage`, `introductoryMessage`), tool config | No | Add prerequisites callout → AI Agents setup guide (`/ai-agents`) — **biggest unreferenced dashboard dependency** | +| 16 | `components/notification-feed` | **Notification Feed** (Campaigns/Notifications) | Both | Campaigns/Notifications configured in Dashboard (channels, categories, templates) | Partial (bottom only) | Promote `/ui-kit/react/campaigns` into an **upfront** prerequisites callout (stated prereqs only mention init+login) | +| 17 | `components/call-buttons` · `incoming-call` · `outgoing-call` · `call-logs` | **Calling components** | Both | Calling add-on enabled on plan + Calls SDK installed + `.setCallingEnabled(true)` | No / Partial | Add prerequisites callout on each → `/ui-kit/react/calling-integration` + `/ui-kit/react/call-features` | +| 18 | `components/message-header` | **Voice/Video call buttons** + `callSettingsBuilder` | Both | Calling enabled; call components mounted; Calls SDK | No | Add `/ui-kit/react/calling-integration` (Step 4 is literally "Add Call Buttons via CometChatMessageHeader") + `/ui-kit/react/call-features` | +| 19 | `components/message-list` | **Agent chat** (`loadLastAgentConversation`, `isAgentChat`) | Both | AI Agent configured | No | Link → `/ui-kit/react/components/ai-assistant-chat` / AI features | +| 20 | `core-features` | **Read Receipts** | Dashboard | Read-receipts setting (also `config={{ hideReceipts }}`) | No | Note dashboard dependency + link `/ui-kit/react/cometchat-provider#with-global-config` | +| 21 | `core-features` | **User Presence** | Both | Presence setting + `subscribePresenceForAllUsers()`; `config={{ hideUserStatus }}` | No | Link → `/ui-kit/react/cometchat-provider` | +| 22 | `core-features` | **Moderation** | Both | Moderation rules in Dashboard | **Yes** → `/moderation/overview` | Adequate (model for others) | +| 23 | `core-features` | **Report Message** | Both | Flagged messages reviewed in Dashboard | **Yes** → `/moderation/flagged-messages` | Adequate | +| 24 | `campaigns` | **Campaigns / Notification Feed** | Both | Channels, categories, templates, campaigns in Dashboard | **Yes** → `/campaigns#setup-flow` | Adequate (model for #16) | +| 25 | `campaigns` | **Push notification tracking** (`markPushNotificationDelivered/Clicked`) | Both | Push Notifications extension (FCM/Web Push) configured | Partial → `/sdk/javascript/campaigns` | Add Push Notifications dashboard-setup guide link | +| 26 | `plugins/overview` | **Extension-backed plugins** (Polls, Stickers, Collab Doc, Collab Whiteboard) | Dashboard | Respective extensions enabled in Dashboard | **No — misleading** ("included automatically — no configuration needed") | Add note + links to each extension guide; this table row is the root of #5–#8 | +| 27 | `plugins/overview` · `event-system` | **AI plugin / `ui:panel/show`,`ui:panel/hide`** (agentic messages) | Both | AI Agents / AI features configured | Partial / No | Link "AI features" → `/ui-kit/react/ai-features` / AI dashboard setup | +| 28 | `cometchat-provider` | **Init & Login** (App ID / Region / Auth Key) | Both | Credentials from Dashboard; `setCallingEnabled`, `subscribePresenceForAllUsers` | Partial | Link to credentials/app-setup guide (`/ui-kit/react/integration-react`) | + +--- + +## Part 2 — Stitching (developer wiring) required + +These do nothing (or nothing useful) until the developer writes connecting code. The docs mostly show inline examples but rarely link to the how-to guide that walks the pattern end-to-end. + +| # | Page | What needs wiring | Type | Ref | Recommended link/reference to add | +|---|------|-------------------|------|-----|-----------------------------------| +| 29 | `components/conversations` | `onItemClick` → derive user/group and mount Header/List/Composer (two-panel) | Stitch | Partial | → `/ui-kit/react/guide-new-chat-creation` near "Full Layout Example" & Next Steps | +| 30 | `components/conversations` | `onSearchBarClicked` → open custom search (`CometChatSearch`) | Stitch | Partial | → `/ui-kit/react/guide-search-messages` | +| 31 | `components/conversations` | `options` menu (Delete/Mute/Pin/Block/Mark-Unread) — `onClick` are placeholders | Stitch | No | Block → `/ui-kit/react/guide-block-unblock-user`; SDK methods for others | +| 32 | `components/conversations` | `ui:message/sent`, `ui:group/*`, `ui:conversation/*` received events | Stitch | No | "Events Received" → `/ui-kit/react/event-system` | +| 33 | `components/users` | `onItemClick` → start conversation / user picker | Stitch | Partial | → `/ui-kit/react/guide-new-chat-creation` | +| 34 | `components/users` | `options` (Block User / View Profile) placeholders | Stitch | No | Block → `/ui-kit/react/guide-block-unblock-user` | +| 35 | `components/users` | `ui:user/blocked` / `ui:user/unblocked` received | Stitch | No | → `/ui-kit/react/event-system` + block/unblock guide | +| 36 | `components/groups` | `onItemClick` → open group chat | Stitch | Partial | → `/ui-kit/react/guide-new-chat-creation` + `/ui-kit/react/guide-group-chat-setup` | +| 37 | `components/groups` | `options` (Leave Group / Group Info) + join/details flows | Stitch | Partial | → `/ui-kit/react/guide-group-chat-setup` | +| 38 | `components/groups` | `ui:group/*` received events | Stitch | No | → `/ui-kit/react/event-system` | +| 39 | `components/group-members` | Required `group` prop (renders nothing without it) | Stitch | Partial | → `/ui-kit/react/guide-group-chat-setup` | +| 40 | `components/group-members` | `onBack` navigation (placeholder) | Stitch | No | Reference navigation/layout how-to | +| 41 | `components/group-members` | Custom `options` (**Message Privately** / Remove), kick/ban/scope overrides | Stitch | No | Message Privately → `/ui-kit/react/guide-message-privately` | +| 42 | `components/group-members` | `ui:group/member-*` / `ownership-changed` received | Stitch | No | → `/ui-kit/react/event-system` | +| 43 | `components/message-header` | `onItemClick` (details panel), `onSearchOptionClicked` (search), `onBack` | Stitch | No | Search → `/ui-kit/react/guide-search-messages`; details → layout how-to | +| 44 | `components/message-list` | Required `user`/`group` entity | Stitch | Partial | → `/ui-kit/react/guide-new-chat-creation` | +| 45 | `components/message-list` | **Thread replies** (`onThreadRepliesClick`, `parentMessageId`) → mount 2nd list/composer | Stitch | Partial (→ Thread Header component) | → `/ui-kit/react/guide-threaded-messages` | +| 46 | `components/message-list` | `onEditMessage`/`onReplyMessage` → composer via `ui:compose/edit`,`ui:compose/reply` | Stitch | No | Edit/Reply Note → `/ui-kit/react/event-system` | +| 47 | `components/message-list` | `goToMessageId` (jump from search / deep link) | Stitch | No | → `/ui-kit/react/guide-search-messages` | +| 48 | `components/message-composer` | Required `user`/`group` entity | Stitch | Partial | → `/ui-kit/react/guide-new-chat-creation` | +| 49 | `components/message-composer` | Edit/Reply mode (`messageToEdit`, `messageToReply`, `ui:compose/*` received) | Stitch | No | Events Received → `/ui-kit/react/event-system` | +| 50 | `components/message-composer` | Custom `attachmentOptions` `onClick`, `sendTextMessageOverride`, custom buttons | Stitch | No | → `/ui-kit/react/plugins/overview`; optimistic-send → event-system | +| 51 | `components/reactions` | Display-only; parent owns add/remove SDK calls, `onReactionClick`, `reactionsRequestBuilder` | Stitch | No | Cross-link Message List (owns SDK calls); avoid legacy `/fundamentals/reactions` | +| 52 | `components/reaction-list` | Parent calls `CometChat.removeReaction`, manages open state, `onItemClick`/`onEmpty` | Stitch | Partial (no Next Steps) | Add cross-links to Reactions + Message List | +| 53 | `components/card-bubble` | `onCardAction` / `ui:card/action` — app owns all action behavior | Stitch | **Yes** (Plugins, Event System) | Adequate; optionally note card source (Bubble Builder / bot) | +| 54 | `components/call-bubble` | `onJoinClick` → start/join call session (empty handler) | Stitch | Partial | Link `onJoinClick` → calling integration / "start a call" | +| 55 | `components/call-buttons` | `callSettingsBuilder` via `CometChatUIKitCalls.CallSettingsBuilder()` | Stitch | No | → calling integration / SDK call-settings reference | +| 56 | `components/outgoing-call` | Required `call` prop; parent manages state (`onOutgoingCallAccepted/Rejected` listeners) | Stitch | Partial | Link "SDK Listeners" note → `/ui-kit/react/calling-integration` | +| 57 | `components/call-logs` | `onCallButtonClicked` re-initiation; `.setAuthToken()` for custom `callLogRequestBuilder` | Stitch | Partial (→ `/sdk/javascript/call-logs`) | Wire re-initiation → call-buttons / calling-integration | +| 58 | `components/search` | Result callbacks → navigation (`onConversationClicked`, `onMessageClicked` → `goToMessageId`) | Stitch | Partial | Note callbacks are required; → Message List / Conversations (+ optionally search guide) | +| 59 | `components/notification-feed` | `onItemClick` / `onActionClick` navigation (deep links, `chatWithUser`/`chatWithGroup`/`openUrl`) | Stitch | Partial | Reference navigation how-to | +| 60 | `core-features` | **Mentions** rendering via `CometChatMentionsFormatter` | Stitch | No | → `/ui-kit/react/plugins/text-formatters#cometchatmentionsformatter` | +| 61 | `core-features` | **Rich Text Formatting** (`enableRichTextEditor` + `CometChatMarkdownFormatter`) | Stitch | Partial | → `/ui-kit/react/plugins/text-formatters` + message-composer | +| 62 | `core-features` | **Threaded Conversations** (wiring required) | Stitch | Partial (mislabeled "Threaded Message Preview") | Clarify wiring; link text → `/ui-kit/react/guide-threaded-messages` | +| 63 | `core-features` | **Conversation & Advanced Search** | Stitch | No | Add → `/ui-kit/react/guide-search-messages` | +| 64 | `campaigns` | Card action handling (`onAction`, 9 action types) | Stitch | Partial | Cross-link `event-system` `ui:card/action` | +| 65 | `plugins/overview` | Custom plugin registration (`CometChatMessagePlugin` via `plugins` prop) | Stitch | Yes | Adequate | +| 66 | `plugins/custom-plugin` | Location plugin walkthrough; `context.publish`; Google Maps API key (external) | Stitch | Partial | `publish` → `/ui-kit/react/event-system`; note Maps API key | +| 67 | `plugins/text-formatters` | Custom formatter must be wrapped in a text plugin + registered via provider | Stitch | Partial | → `/ui-kit/react/plugins/overview` + `/ui-kit/react/cometchat-provider#with-additional-plugins` | +| 68 | `event-system` | Guides depend on events but tables don't link back | Stitch | Partial | See Part 3 §D (bidirectional links) | +| 69 | `guide-block-unblock-user` | Uses `usePublishEvent`/`useCometChatEvents` + `ui:user/blocked`,`ui:user/unblocked` | Stitch | Partial | Add → `/ui-kit/react/event-system` | +| 70 | `guide-message-privately` | Hinges on `ui:open-chat` event (published by Message List "Message Privately") | Stitch | Partial | Add → `/ui-kit/react/event-system#navigation` | + +--- + +## Part 3 — Systemic / high-priority patterns + +### A. `plugins/overview` says "no configuration needed" — misleading for extension-backed content +All four extension bubbles (Poll, Sticker, Collaborative Document, Collaborative Whiteboard) route their "how it works" reference through `plugins/overview#built-in-plugins`, which states plugins are *"included automatically — no configuration needed."* That's true for the UI Kit **renderer** but false for the **Dashboard extension** that produces the message. **Fix once at the source** (add a "Requires the X extension enabled in the Dashboard" note + link on the `extension_*` rows), then add the same note on each bubble page (#5–#8, #26). + +### B. Calling pages have no upfront prerequisites +`call-buttons`, `incoming-call`, `outgoing-call`, `call-logs` never mention the Calls SDK install or `.setCallingEnabled(true)` on their own page, and don't link to `calling-integration`/`call-features`. A reader can copy the minimal render and see **nothing render**. Also: `call-features.mdx` (the overview) omits a link to `calling-integration.mdx` (the actual step-by-step setup), and `calling-integration.mdx` doesn't link out to the standalone `call-buttons`/`incoming-call`/`outgoing-call` component pages. (#17, #18, #54–#57) + +### C. AI ("Smart Chat") features are never linked from component pages +`ai-features.mdx` exists but is not linked from `message-header` (Summary), `message-list` (Smart Replies, Conversation Starters), or `message-composer` (AI button). `ai-assistant-chat` has **no** link to any AI-Agent Dashboard-setup guide despite requiring a Dashboard-configured agent user. (#11–#15, #19, #27) + +### D. Event-system ↔ guide links are missing in both directions +`event-system.mdx` lists events that power the guides but links to none of them; the guides use the events but don't link back: +- `ui:user/blocked` / `ui:user/unblocked` ↔ `guide-block-unblock-user` +- `ui:open-chat` ↔ `guide-message-privately` +- `ui:thread/opened` / `ui:thread/closed` ↔ `guide-threaded-messages` +- `ui:group/created` ↔ `guide-group-chat-setup` + +Also, no component page ("Events Received/Emitted" tables) links to `event-system.mdx` at all. (#32, #35, #38, #42, #46, #49, #68–#70) + +### E. Content-integrity contradiction (flag for docs owner) +Plugin registration order conflicts across pages: +- `plugins/text-formatters.mdx` (line ~142): custom plugins are **"prepended before the defaults… your custom text plugin takes precedence."** +- `plugins/overview.mdx` (~line 76) and `plugins/custom-plugin.mdx` (~line 124): custom plugins are **"appended after the defaults, so default plugins keep priority."** + +These directly disagree on ordering. Not a dashboard/stitch gap, but it will confuse anyone wiring a custom formatter — reconcile before adding more cross-links. + +--- + +## Part 4 — Guide pages available to link to (inventory) + +| Guide page | Walks through | Primary components | +|------------|---------------|--------------------| +| `guide-new-chat-creation` | Start 1:1/group chats: `onItemClick`, tab state, conditional `joinGroup()`, first-message send | Users, Groups, Conversations | +| `guide-group-chat-setup` | Create/join/add-members: `createGroup()`, `joinGroup()`, `addMembersToGroup()` | Groups, Group Members, Message Header | +| `guide-threaded-messages` | Thread panel: `onThreadRepliesClick`, `parentMessageId`, `CometChatThreadHeader` | Message List, Thread Header | +| `guide-search-messages` | In-conversation search: `CometChatSearch` → `goToMessageId` | Search, Message List, Message Header | +| `guide-block-unblock-user` | Block/unblock via SDK + `ui:user/blocked`/`unblocked` events | Message Composer, Conversations | +| `guide-message-privately` | Private DM from group via `ui:open-chat` event | Message Composer, Users, Conversations | +| `extensions` | All Dashboard extensions + which component each auto-integrates into | Composer, Message List | +| `ai-features` (Smart Chat) | Conversation Starter, Smart Replies, Conversation Summary | Message List, Composer, AI Assistant Chat | +| `calling-integration` | End-to-end calling setup (SDK install, `setCallingEnabled`, incoming placement) | Message Header, Call components | +| `call-features` | Calling overview | Call components | +| `campaigns` | Campaigns/notifications end-to-end | Notification Feed | +| `event-system` | Pub/sub, `useCometChatEvents`, `usePublishEvent`, all `ui:*` events | All | + +--- + +## Summary + +- **Files audited:** ~50 (all React v7 UI Kit `.mdx`). +- **Total findings:** ~70 (28 dashboard-enablement, ~42 stitching; overlaps counted once by primary type). +- **Dashboard-enable (pure):** message-list Translate & Flag/Moderation, composer Polls/Collab/Stickers & file limits, sticker bubble, video thumbnails, core-features read-receipts, plugins/overview extension plugins. +- **Both (dashboard + stitch):** all calling components & header call buttons, all AI features (Summary, Smart Replies, Starters, AI button, AI Assistant Chat, agent chat), poll/collab-doc/collab-whiteboard bubbles, flag dialog, campaigns/notification-feed, presence, provider init. +- **Missing a reference entirely (`No`) or only `Partial`:** the large majority — the six how-to guides, `extensions.mdx`, `ai-features.mdx`, `calling-integration.mdx`/`call-features.mdx`, and `event-system.mdx` all exist but are **rarely linked from the component pages they explain**. + +**Top 6 fixes (highest impact):** +1. `plugins/overview` — correct the "no configuration needed" line for Polls/Stickers/Collab Doc/Collab Whiteboard; link each extension guide (fixes 5 pages at the source). +2. `ai-assistant-chat` — add AI-Agent Dashboard-setup prerequisites callout (completely unreferenced dashboard dependency). +3. Calling components (`call-buttons`, `incoming-call`, `outgoing-call`, `call-logs`) — add upfront prerequisites callout → `calling-integration` + `call-features`. +4. `message-header` / `message-list` / `message-composer` — link AI props → `ai-features`, extension attachments/translate → `extensions`. +5. `call-features` → link `calling-integration`; `calling-integration` → link the standalone call component pages. +6. Add bidirectional `event-system` ↔ guide links (block/unblock, message-privately, threads, group-created) and link component "Events Received" tables → `event-system`. diff --git a/ui-kit/react/campaigns.mdx b/ui-kit/react/campaigns.mdx index 71080b1ec..2ae7340ac 100644 --- a/ui-kit/react/campaigns.mdx +++ b/ui-kit/react/campaigns.mdx @@ -51,6 +51,10 @@ The Cards library is a **pure renderer**: It does not execute actions, manage message state, or call any SDK methods. When users click interactive elements (buttons, links), the library emits the action to your callback. You decide what happens — open a URL, navigate to a chat, make an API call, etc. + +When wiring the `onAction` callback, handle each action type (`openUrl`, `chatWithUser`, `chatWithGroup`, `sendMessage`, and the rest) explicitly in your own code. For the recommended pattern of turning card actions into app behavior, see [Event System — Card Actions](/ui-kit/react/event-system#card-actions). + + ### Card Schema JSON Example ```json @@ -147,6 +151,10 @@ You don't need to interact with the Cards library directly when using `CometChat ## Handling Push Notifications for Campaigns + +**Prerequisite: Push Notifications must be configured first.** The tracking calls below only apply once you have set up a push provider (**FCM** or **Web Push**) and are receiving campaign pushes. Start with [Web Push Notifications setup](/notifications/web-push-notifications), and see the [Push Notifications overview](/notifications/push-overview) for provider options and the delivery pipeline. + + When a campaign push notification arrives via Web Push or FCM, you should: 1. **Report delivery** — Call `CometChat.markPushNotificationDelivered()` when the notification is received diff --git a/ui-kit/react/components/ai-assistant-chat.mdx b/ui-kit/react/components/ai-assistant-chat.mdx index ed52d939e..eff675a3a 100644 --- a/ui-kit/react/components/ai-assistant-chat.mdx +++ b/ui-kit/react/components/ai-assistant-chat.mdx @@ -4,95 +4,32 @@ description: "AI agent chat interface with streaming responses, suggested messag --- -```json -{ - "component": "CometChatAIAssistantChat", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatAIAssistantChat } from \"@cometchat/chat-uikit-react\";", - "description": "AI agent chat interface with streaming responses, suggested messages, tool calling, and conversation history.", - "cssRootClass": ".cometchat-ai-assistant-chat", - "primaryOutput": { - "prop": "onSendButtonClick", - "type": "(message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "REQUIRED", - "note": "The AI assistant user entity" - }, - "streamingSpeed": { - "type": "number", - "default": 30, - "note": "Milliseconds between text chunks during streaming" - }, - "aiAssistantTools": { - "type": "CometChatAIAssistantTools", - "default": "undefined", - "note": "Tool handlers for AI function calls" - }, - "loadLastAgentConversation": { - "type": "boolean", - "default": false - }, - "suggestedMessages": { - "type": "string[]", - "default": "[] (falls back to user metadata)" - }, - "parentMessageId": { - "type": "number", - "default": "undefined", - "note": "Load a specific conversation thread" - } - }, - "callbacks": { - "onSendButtonClick": "(message: CometChat.BaseMessage) => void", - "onBackButtonClicked": "() => void", - "onCloseButtonClicked": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideSuggestedMessages": { "type": "boolean", "default": false }, - "hideChatHistory": { "type": "boolean", "default": false }, - "hideNewChat": { "type": "boolean", "default": false }, - "showBackButton": { "type": "boolean", "default": false }, - "showCloseButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "emptyChatImageView": "ReactNode", - "emptyChatGreetingView": "ReactNode", - "emptyChatIntroMessageView": "ReactNode", - "emptyView": "ReactNode", - "loadingView": "ReactNode", - "errorView": "ReactNode", - "headerItemView": "ReactNode", - "headerTitleView": "ReactNode", - "headerSubtitleView": "ReactNode", - "headerLeadingView": "ReactNode", - "headerTrailingView": "ReactNode", - "headerAuxiliaryButtonView": "ReactNode" - } - }, - "events": [ - { - "name": "ui:compose/text", - "payload": "{ text }", - "description": "Suggestion pill clicked (sets text in composer)" - } - ], - "sdkListeners": [], - "types": { - "CometChatAIAssistantTools": "Class — maps tool function names to handler functions via constructor(actions: Record) => void>)" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatAIAssistantChat` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-ai-assistant-chat` | +| Primary output | `onSendButtonClick: (message: CometChat.BaseMessage) => void` — emits the sent user message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus an [AI Agent](/ai-agents/agent-builder/overview) configured in the Dashboard (passed as the `user` prop) | +| Stitching | Pass the AI Agent's `user` entity; the component streams replies and handles tool calls internally | +| Events emitted | `ui:compose/text` — sets text in the composer when a suggestion pill is clicked — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | None directly; internally uses the message list's SDK listeners for message updates, plus an AI assistant listener for streaming replies | +| Full props | See [Props](#props) | + ## Overview `CometChatAIAssistantChat` is an AI agent chat interface. It renders a full chat experience with streaming responses, suggested message pills, tool calling support, and a conversation history sidebar. Pass a `CometChat.User` representing the AI assistant and the component handles the rest — message threading, streaming display, and composer integration. + +**Prerequisite: an AI Agent must be configured in the CometChat Dashboard.** This component renders nothing useful without one. `CometChatAIAssistantChat` requires an **AI Agent set up in the Dashboard as a `CometChat.User`**, and the `user` prop must be that agent's user entity. The agent's replies, tool execution, and metadata — including `suggestedMessages`, `greetingMessage`, `introductoryMessage`, and tool configuration — are defined when you create the agent. + +Set up the agent with the [AI Agent Builder](/ai-agents/agent-builder/overview). + + **1:1 and group conversations.** AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are delivered and attributed like any other member's message. If the group contains only one user and one agent, the agent responds automatically. In groups with more than two members, the agent only responds when @mentioned. diff --git a/ui-kit/react/components/audio-bubble.mdx b/ui-kit/react/components/audio-bubble.mdx index 0c2a1e774..18d981e4b 100644 --- a/ui-kit/react/components/audio-bubble.mdx +++ b/ui-kit/react/components/audio-bubble.mdx @@ -5,25 +5,18 @@ description: "A batch-aware bubble that renders one or more audio file attachmen --- -```json -{ - "component": "CometChatAudiosBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatAudiosBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware audio bubble for attached audio files. Renders stacked audio cards with play/pause, seekable slider, duration, and download. NOT used for voice notes — see CometChatVoiceNoteBubble.", - "cssRootClass": ".cometchat-audios-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of audio attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatAudiosBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatAudiosBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-audios-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/call-action-bubble.mdx b/ui-kit/react/components/call-action-bubble.mdx index 16032d5a1..c6dc8dfa6 100644 --- a/ui-kit/react/components/call-action-bubble.mdx +++ b/ui-kit/react/components/call-action-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble that renders call status system messages --- -```json -{ - "component": "CometChatCallActionBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallActionBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting bubble for call status system messages. Derives the status text, icon, and error color from the SDK call message and the logged-in user.", - "cssRootClass": ".cometchat-action-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The call message (audio/video) in the 'call' category. Drives all extraction." }, - "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" } - } - }, - "rendersThrough": "CometChatActionBubble (base primitive)", - "usedBy": ["CometChatCallActionPlugin"] -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallActionBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallActionBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-action-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/call-bubble.mdx b/ui-kit/react/components/call-bubble.mdx index 8a5bd8541..c4e6b8eae 100644 --- a/ui-kit/react/components/call-bubble.mdx +++ b/ui-kit/react/components/call-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble for direct-call / meeting messages, with --- -```json -{ - "component": "CometChatCallBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting call bubble for meeting / direct-call custom messages. Derives the call type, session ID, title, icon, and timestamp from the message.", - "cssRootClass": ".cometchat-call-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The meeting/direct-call message; drives extraction." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onJoinClick": { "type": "(sessionId: string) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-bubble` | +| Primary output | Self-extracting call bubble; `onJoinClick: (sessionId: string) => void` starts the call on Join | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; see [Calling Integration](/ui-kit/react/calling-integration) to start/join a call session | +| Stitching | Wire `onJoinClick` to start the call (see [Calling Integration](/ui-kit/react/calling-integration)) | +| Full props | See [Props](#props) | + ## Overview @@ -92,7 +86,11 @@ Override incoming/outgoing alignment. Defaults to sender-vs-logged-in-user. ### onJoinClick -Callback when the Join button is clicked. Receives the session ID. +Callback when the Join button is clicked. Receives the session ID. Empty by default — you must start or join the call session yourself. + + +See [Calling Integration](/ui-kit/react/calling-integration) for how to start or join a call session. + | | | | --- | --- | diff --git a/ui-kit/react/components/call-buttons.mdx b/ui-kit/react/components/call-buttons.mdx index 33e323647..50de83487 100644 --- a/ui-kit/react/components/call-buttons.mdx +++ b/ui-kit/react/components/call-buttons.mdx @@ -4,85 +4,21 @@ description: "Voice and video call buttons for user or group conversations, with --- -```json -{ - "component": "CometChatCallButtons", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallButtons } from \"@cometchat/chat-uikit-react\";", - "description": "Voice and video call initiation buttons for user or group conversations. Manages the full call lifecycle (outgoing + ongoing) internally.", - "cssRootClass": ".cometchat-call-buttons", - "primaryOutput": { - "description": "Initiates calls via the SDK and renders the outgoing/ongoing call screens" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "Pass either user or group, not both" - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "Pass either user or group, not both" - } - }, - "callbacks": { - "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onCallEnded": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideVoiceCallButton": { "type": "boolean", "default": false }, - "hideVideoCallButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "voiceCallButtonView": "ReactNode", - "videoCallButtonView": "ReactNode" - }, - "configuration": { - "callSettingsBuilder": "(isAudioOnlyCall: boolean, user?: CometChat.User, group?: CometChat.Group) => CallSettingsBuilder", - "className": "string" - } - }, - "eventsEmitted": [ - { - "name": "ui:call/outgoing", - "payload": "{ call }", - "description": "User initiates a 1-on-1 voice/video call" - }, - { - "name": "ui:message/sent", - "payload": "{ message, status }", - "description": "Group call meeting message sent" - } - ], - "eventsReceived": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Re-enables call buttons after the call is rejected" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets all call state when the call ends" - } - ], - "sdkListeners": [ - "onIncomingCallReceived", - "onIncomingCallCancelled", - "onOutgoingCallAccepted", - "onOutgoingCallRejected" - ], - "compositionExample": { - "description": "Standalone call buttons or embedded in the MessageHeader auxiliary view", - "components": ["CometChatCallButtons", "CometChatOutgoingCall", "CometChatOngoingCall"], - "flow": "user/group prop -> click button -> SDK initiateCall -> CometChatOutgoingCall overlay -> onOutgoingCallAccepted -> CometChatOngoingCall" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallButtons` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallButtons } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-buttons` | +| Primary output | Initiates voice/video calls via the SDK and renders the outgoing/ongoing call screens; `onVoiceCallClick` / `onVideoCallClick` override the default initiation | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the Calls SDK installed and calling enabled — see [Calling Integration](/ui-kit/react/calling-integration) | +| Stitching | Pass `user` or `group`; the buttons manage the outgoing/ongoing call lifecycle internally (see [Calling Integration](/ui-kit/react/calling-integration)) | +| Events emitted | `ui:call/outgoing`, `ui:message/sent` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Incoming call events (received/cancelled) and outgoing call events (accepted/rejected) to sync button state and screen transitions | +| Full props | See [Props](#props) | + ## Where It Fits @@ -417,7 +353,7 @@ All props are optional. Sorted alphabetically. ### callSettingsBuilder -Builder function for customizing the ongoing call settings. +Builder function for customizing the ongoing call settings, built via `callSettings`. See [Calling Integration](/ui-kit/react/calling-integration) for call-settings setup. | | | | --- | --- | diff --git a/ui-kit/react/components/call-logs.mdx b/ui-kit/react/components/call-logs.mdx index 5f30f2500..a06ef9c68 100644 --- a/ui-kit/react/components/call-logs.mdx +++ b/ui-kit/react/components/call-logs.mdx @@ -4,85 +4,19 @@ description: "Scrollable list of call history with call details, duration, and t --- -```json -{ - "component": "CometChatCallLogs", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCallLogs } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of call history with call details, duration, and the ability to initiate new calls.", - "cssRootClass": ".cometchat-call-logs", - "primaryOutput": { - "prop": "onItemClick", - "type": "(call: any) => void" - }, - "props": { - "data": { - "activeCall": { - "type": "any", - "default": "undefined", - "note": "Object representing the active/selected call log" - }, - "callLogRequestBuilder": { - "type": "any", - "default": "limit 30, category \"call\"", - "note": "Custom request builder for filtering call logs" - }, - "callInitiatedDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older" - } - }, - "callbacks": { - "onItemClick": "(call: any) => void", - "onCallButtonClicked": "(call: any) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "configuration": { - "callSettingsBuilder": { - "type": "any", - "default": "undefined", - "note": "Custom call settings builder for ongoing call sessions initiated from call logs" - } - }, - "visibility": { - "showScrollbar": { "type": "boolean", "default": false } - }, - "viewSlots": { - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "itemView": "(call: any) => ReactNode", - "leadingView": "(call: any) => ReactNode", - "titleView": "(call: any) => ReactNode", - "subtitleView": "(call: any) => ReactNode", - "trailingView": "(call: any) => ReactNode" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets ongoing call state (hides call screen)" - } - ], - "sdkListeners": [], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCallLogs` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCallLogs } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-call-logs` | +| Primary output | `onItemClick: (call: any) => void` — emits the selected call log | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Wire `onItemClick` / `onCallButtonClicked` to open details or start a call | +| Events received | `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/card-bubble.mdx b/ui-kit/react/components/card-bubble.mdx index dc52fc66f..6790cc68d 100644 --- a/ui-kit/react/components/card-bubble.mdx +++ b/ui-kit/react/components/card-bubble.mdx @@ -5,24 +5,18 @@ description: "A render-only bubble that draws developer-defined card messages (c --- -```json -{ - "component": "CometChatCardBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCardBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Render-only bubble for developer card messages (category \"card\"). Stringifies the raw payload from message.getCard() and hands it to the prebuilt CometChatCardView renderer, then forwards user actions back to the app. It never parses, mutates, or acts on the card itself.", - "cssRootClass": ".cometchat-card-bubble", - "renderOnly": true, - "props": { - "data": { - "message": { "type": "CometChat.CardMessage", "required": true, "note": "The developer card message (category \"card\"). Drives message.getCard()." }, - "themeMode": { "type": "CometChatCardThemeMode", "default": "\"auto\"", "note": "Theme mode forwarded to CometChatCardView." }, - "themeOverride": { "type": "CometChatCardThemeOverride", "note": "Optional theme overrides forwarded to the renderer." }, - "onCardAction": { "type": "(message: CometChat.BaseMessage, action: CometChatCardAction) => void", "note": "Direct callback for card actions, fired in addition to the ui:card/action event." } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCardBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCardBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-card-bubble` | +| Primary output | `onCardAction: (message: CometChat.BaseMessage, action: CometChatCardAction) => void` — forwards the user's card action | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/collaborative-document-bubble.mdx b/ui-kit/react/components/collaborative-document-bubble.mdx index daeeef335..4bc808e9d 100644 --- a/ui-kit/react/components/collaborative-document-bubble.mdx +++ b/ui-kit/react/components/collaborative-document-bubble.mdx @@ -5,31 +5,28 @@ description: "A self-extracting bubble that renders a collaborative document car --- -```json -{ - "component": "CometChatCollaborativeDocumentBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCollaborativeDocumentBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting collaborative document bubble. Extracts the document URL from the message metadata and opens it on click.", - "cssRootClass": ".cometchat-collaborative-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the document URL." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." }, - "disabled": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCollaborativeDocumentBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCollaborativeDocumentBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-collaborative-bubble` | +| Primary output | `onButtonClick: (url: string) => void` — opens the document URL (defaults to `window.open`) | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Collaborative Document extension](/fundamentals/collaborative-document) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview `CometChatCollaborativeDocumentBubble` renders a collaborative document card — a banner image, a title, a subtitle, and an "Open Document" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the document URL from the message's extension metadata (`@injected.extensions.document.document_url`), so it works standalone. Clicking the button opens the document (by default in a new window). + +**Requires the Collaborative Document extension enabled in the [CometChat Dashboard](/fundamentals/collaborative-document).** Document messages (`extension_document`) — and the injected `document_url` this bubble reads — are only produced once the extension is turned on for your app. Without it the composer cannot create documents and this bubble never renders. See the [Collaborative Document guide](/fundamentals/collaborative-document) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes document messages to this bubble. + + **Live Preview** — interact with the collaborative document bubble. @@ -137,6 +134,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the extension that produces these messages + Render collaborative whiteboard messages diff --git a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx index 7ad4dd731..8b0cb0741 100644 --- a/ui-kit/react/components/collaborative-whiteboard-bubble.mdx +++ b/ui-kit/react/components/collaborative-whiteboard-bubble.mdx @@ -5,31 +5,28 @@ description: "A self-extracting bubble that renders a collaborative whiteboard c --- -```json -{ - "component": "CometChatCollaborativeWhiteboardBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatCollaborativeWhiteboardBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting collaborative whiteboard bubble. Extracts the board URL from the message metadata and opens it on click.", - "cssRootClass": ".cometchat-collaborative-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "Drives extraction of the board URL." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "onButtonClick": { "type": "(url: string) => void", "note": "Defaults to window.open." }, - "disabled": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatCollaborativeWhiteboardBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatCollaborativeWhiteboardBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-collaborative-bubble` | +| Primary output | Self-extracting; primary callback `onButtonClick: (url: string) => void` opens the whiteboard URL (defaults to `window.open`). | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Collaborative Whiteboard extension](/fundamentals/collaborative-whiteboard) enabled in the Dashboard. | +| Stitching | None — self-extracting from the SDK message. | +| Full props | See [Props](#props). | + ## Overview `CometChatCollaborativeWhiteboardBubble` renders a collaborative whiteboard card — a banner image, a title, a subtitle, and an "Open Whiteboard" button. It is **self-extracting**: pass the SDK `message` and the bubble reads the board URL from the message's extension metadata (`@injected.extensions.whiteboard.board_url`), so it works standalone. Clicking the button opens the whiteboard (by default in a new window). + +**Requires the Collaborative Whiteboard extension enabled in the [CometChat Dashboard](/fundamentals/collaborative-whiteboard).** Whiteboard messages (`extension_whiteboard`) — and the injected `board_url` this bubble reads — are only produced once the extension is turned on for your app. Without it the composer cannot create whiteboards and this bubble never renders. See the [Collaborative Whiteboard guide](/fundamentals/collaborative-whiteboard) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes whiteboard messages to this bubble. + + **Live Preview** — interact with the collaborative whiteboard bubble. @@ -137,6 +134,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the extension that produces these messages + Render collaborative document messages diff --git a/ui-kit/react/components/conversations.mdx b/ui-kit/react/components/conversations.mdx index a40324853..b3af4e9fc 100644 --- a/ui-kit/react/components/conversations.mdx +++ b/ui-kit/react/components/conversations.mdx @@ -4,129 +4,21 @@ description: "Scrollable list of recent one-on-one and group conversations for t --- -```json -{ - "component": "CometChatConversations", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatConversations } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of recent one-on-one and group conversations for the logged-in user with real-time updates.", - "cssRootClass": ".cometchat-conversations", - "primaryOutput": { - "prop": "onItemClick", - "type": "(conversation: CometChat.Conversation) => void" - }, - "props": { - "data": { - "conversationsRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeConversation": { - "type": "CometChat.Conversation", - "default": "undefined" - }, - "lastMessageDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "hh:mm A today, Yesterday, dddd last week, DD/MM/YYYY older" - } - }, - "callbacks": { - "onItemClick": "(conversation: CometChat.Conversation) => void", - "onSelect": "(conversation: CometChat.Conversation, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void", - "onSearchBarClicked": "() => void" - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideUserStatus": { "type": "boolean", "default": false }, - "hideGroupType": { "type": "boolean", "default": false }, - "hideUnreadCount": { "type": "boolean", "default": false }, - "hideDeleteConversation": { "type": "boolean", "default": false }, - "showSearchBar": { "type": "boolean", "default": true }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "sound": { - "disableSoundForMessages": { "type": "boolean", "default": false }, - "customSoundForMessages": { "type": "string", "default": "built-in" } - }, - "selection": { - "selectionMode": { - "type": "CometChatConversationsSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(conversation: CometChat.Conversation) => ReactNode", - "leadingView": "(conversation: CometChat.Conversation) => ReactNode", - "titleView": "(conversation: CometChat.Conversation) => ReactNode", - "subtitleView": "(conversation: CometChat.Conversation) => ReactNode", - "trailingView": "(conversation: CometChat.Conversation) => ReactNode", - "headerView": "ReactNode", - "searchView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(conversation: CometChat.Conversation) => CometChatConversationOption[]" - } - }, - "events": [ - { - "name": "ui:conversation/deleted", - "payload": "{ conversation: CometChat.Conversation }", - "description": "Conversation deleted from list" - } - ], - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onTypingStarted", - "onTypingEnded", - "onMessagesDelivered", - "onMessagesRead", - "onUserOnline", - "onUserOffline", - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - }, - "CometChatConversationOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(conversation: CometChat.Conversation) => void" - }, - "CometChatConversationsSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatConversations` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatConversations } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-conversations` | +| Primary output | `onItemClick: (conversation: CometChat.Conversation) => void` — emits the selected conversation to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Wire `onItemClick` → derive the user/group with `conversation.getConversationWith()` → mount `CometChatMessageHeader` / `CometChatMessageList` / `CometChatMessageComposer` (see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation)). Full search needs `onSearchBarClicked` → [`CometChatSearch`](/ui-kit/react/components/search) (see the [Search Messages guide](/ui-kit/react/guide-search-messages)) | +| Events emitted | `ui:conversation/deleted` — see the [Event System](/ui-kit/react/event-system) | +| Events received | Subscribes to `ui:message/*`, `ui:conversation/*`, and `ui:group/*` events published by other components — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Messages, typing, receipts, presence, and group membership are handled internally — no wiring needed | +| Full props | See [Props](#props) | + ## Overview @@ -200,6 +92,8 @@ function Sidebar() { ### Full Layout Example +`onItemClick` is where you derive the selected user or group from the conversation and mount the `MessageHeader` / `MessageList` / `MessageComposer` panel — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the full two-panel wiring. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -276,6 +170,8 @@ To use the search bar as a trigger for a custom search UI (like `CometChatSearch /> ``` +See the [Search Messages guide](/ui-kit/react/guide-search-messages) for wiring a full search experience across conversations and messages. + ### Filter Recipes | Recipe | Code | @@ -309,7 +205,7 @@ UI events this component publishes: ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see the [Event System](/ui-kit/react/event-system) for how components publish and subscribe. | Event | Payload | Behavior | | --- | --- | --- | @@ -863,6 +759,10 @@ function CustomOptionsConversations() { return ; } ``` + + +The `onClick` handlers above are placeholders — the component only renders the menu items; you must implement the actual behavior (delete, mute, pin, mark-unread, block). For the Block option, wire it to the SDK and refresh UI state as shown in the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). + ```css @@ -1048,6 +948,10 @@ Whether to show the search bar. Set to `false` to hide it entirely. | Type | `boolean` | | Default | `true` | + +Showing the bar is not the same as enabling search. To power a full **conversation + message search** experience you need two more things: (1) enable **Conversation & Advanced Search** for your app in the [CometChat Dashboard](https://app.cometchat.com), and (2) wire the bar as a trigger — pass [`onSearchBarClicked`](#onsearchbarclicked) to open a [`CometChatSearch`](/ui-kit/react/components/search) panel and switch views. See the [Search Messages guide](/ui-kit/react/guide-search-messages) for the full wiring across conversations and messages. + + --- ### showScrollbar diff --git a/ui-kit/react/components/delete-bubble.mdx b/ui-kit/react/components/delete-bubble.mdx index 87511df46..fb0812883 100644 --- a/ui-kit/react/components/delete-bubble.mdx +++ b/ui-kit/react/components/delete-bubble.mdx @@ -5,22 +5,18 @@ description: "A presentational bubble that renders a 'This message was deleted' --- -```json -{ - "component": "CometChatDeleteBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatDeleteBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Presentational placeholder bubble for deleted messages.", - "cssRootClass": ".cometchat-delete-bubble", - "props": { - "data": { - "isSentByMe": { "type": "boolean", "note": "Affects sent vs received styling." }, - "text": { "type": "string", "note": "Defaults to localized \"This message was deleted\"." }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatDeleteBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatDeleteBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-delete-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/file-bubble.mdx b/ui-kit/react/components/file-bubble.mdx index f5d4e97a8..51d037af9 100644 --- a/ui-kit/react/components/file-bubble.mdx +++ b/ui-kit/react/components/file-bubble.mdx @@ -5,25 +5,18 @@ description: "A batch-aware bubble that renders one or more generic file attachm --- -```json -{ - "component": "CometChatFilesBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatFilesBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware file bubble. Extracts file attachments and caption from a MediaMessage; renders stacked file cards with type icons, name, size, extension, and download. Collapses to 3 cards with '+N more' expander.", - "cssRootClass": ".cometchat-files-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of file attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatFilesBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatFilesBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-files-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/flag-message-dialog.mdx b/ui-kit/react/components/flag-message-dialog.mdx index b5d5ef220..6d5336dbf 100644 --- a/ui-kit/react/components/flag-message-dialog.mdx +++ b/ui-kit/react/components/flag-message-dialog.mdx @@ -5,42 +5,18 @@ description: "A dialog for reporting inappropriate messages with reason selectio --- -```json -{ - "component": "CometChatFlagMessageDialog", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatFlagMessageDialog } from \"@cometchat/chat-uikit-react\";", - "description": "Dialog for reporting/flagging an inappropriate message. Fetches flag reasons from the SDK, captures an optional remark, and submits the report.", - "cssRootClass": ".cometchat-flag-message-dialog", - "primaryOutput": { - "prop": "onSubmit", - "type": "(messageId: string, reasonId: string, remark?: string) => Promise" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message being flagged." }, - "isOpen": { "type": "boolean", "note": "When provided, the dialog is controlled." } - }, - "callbacks": { - "onSubmit": { "type": "(messageId: string, reasonId: string, remark?: string) => Promise", "note": "Return true to close, false to keep open and show an error." }, - "onClose": { "type": "() => void" }, - "onError": { "type": "((error: CometChat.CometChatException) => void) | null" } - }, - "config": { - "closeOnOutsideClick": { "type": "boolean", "default": true }, - "className": { "type": "string" } - } - }, - "types": { - "CometChatFlagMessageDialogRootProps": "Root overlay props", - "CometChatFlagMessageDialogHeaderProps": "Header sub-component props", - "CometChatFlagMessageDialogReasonsProps": "Reasons list sub-component props", - "CometChatFlagMessageDialogRemarkProps": "Remark input sub-component props", - "CometChatFlagMessageDialogActionsProps": "Actions (cancel/submit) sub-component props", - "CometChatFlagMessageDialogContextValue": "Full context value" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatFlagMessageDialog` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatFlagMessageDialog } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-flag-message-dialog` | +| Primary output | `onSubmit: (messageId: string, reasonId: string, remark?: string) => Promise` — submits the flag report | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; implement `onSubmit` (return `true` to close) and `onClose` to dismiss | +| Full props | See [Props](#props) | + ## Where It Fits @@ -226,6 +202,10 @@ Called when an SDK error occurs (e.g., while fetching reasons or during submissi On open, the dialog calls `CometChat.getFlagReasons()` and renders the result as a single-select list. While loading, a loading state is shown. If the call fails, `onError` is invoked. + +Report reasons come from your CometChat **Moderation / Report Message** configuration in the Dashboard, fetched via `CometChat.getFlagReasons()`. Configure custom reasons and review flagged messages in [Moderation](/moderation/overview). The parent component must implement `onSubmit` to submit the report. + + ### Remark The remark is optional. It is trimmed before submission, and an empty remark is passed as `undefined` to `onSubmit`. A character counter enforces `maxLength` (default 500). diff --git a/ui-kit/react/components/group-action-bubble.mdx b/ui-kit/react/components/group-action-bubble.mdx index 64b9882e5..190edd8fb 100644 --- a/ui-kit/react/components/group-action-bubble.mdx +++ b/ui-kit/react/components/group-action-bubble.mdx @@ -5,24 +5,18 @@ description: "A self-extracting bubble that renders group action system messages --- -```json -{ - "component": "CometChatGroupActionBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroupActionBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting bubble for group membership system messages. Derives the localized action text from the SDK group-action message.", - "cssRootClass": ".cometchat-action-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true, "note": "The group-action message (member joined/left/added/kicked/banned/scope change). Drives all extraction." }, - "className": { "type": "string", "default": "undefined", "note": "Additional CSS class for the root element" } - } - }, - "rendersThrough": "CometChatActionBubble (base primitive)", - "usedBy": ["CometChatGroupActionPlugin"] -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroupActionBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroupActionBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-action-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/group-members.mdx b/ui-kit/react/components/group-members.mdx index f70cd3a55..0da173864 100644 --- a/ui-kit/react/components/group-members.mdx +++ b/ui-kit/react/components/group-members.mdx @@ -4,120 +4,20 @@ description: "Scrollable list of members for a specific group with role-based ac --- -```json -{ - "component": "CometChatGroupMembers", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroupMembers } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable list of members for a specific group with role-based actions like kick, ban, and scope change.", - "cssRootClass": ".cometchat-group-members", - "primaryOutput": { - "prop": "onItemClick", - "type": "(member: CometChat.GroupMember) => void" - }, - "props": { - "data": { - "group": { - "type": "CometChat.Group", - "default": "none (required)", - "note": "The group whose members to display" - }, - "groupMemberRequestBuilder": { - "type": "CometChat.GroupMembersRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.GroupMembersRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(member: CometChat.GroupMember) => void", - "onSelect": "(member: CometChat.GroupMember, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void", - "onBack": "() => void" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "hideKickMemberOption": { "type": "boolean", "default": false }, - "hideBanMemberOption": { "type": "boolean", "default": false }, - "hideScopeChangeOption": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatGroupMembersSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(member: CometChat.GroupMember) => ReactNode", - "leadingView": "(member: CometChat.GroupMember) => ReactNode", - "titleView": "(member: CometChat.GroupMember) => ReactNode", - "subtitleView": "(member: CometChat.GroupMember) => ReactNode", - "trailingView": "(member: CometChat.GroupMember) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(member: CometChat.GroupMember) => CometChatGroupMemberOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:group/member-added", - "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }", - "description": "Adds new members to the list" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Removes the kicked member from the list" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Removes the banned member from the list" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }", - "description": "Updates the member's scope/role display" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates new owner's scope to owner and demotes previous owner to admin" - } - ], - "sdkListeners": [ - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onGroupMemberScopeChanged", - "onMemberAddedToGroup" - ], - "types": { - "CometChatGroupMemberOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(member: CometChat.GroupMember) => void" - }, - "CometChatGroupMembersSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroupMembers` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroupMembers } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-group-members` | +| Primary output | `onItemClick: (member: CometChat.GroupMember) => void` — emits the selected group member | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `group`; wire `onItemClick` (or `onSelect` in selection mode) to act on a member | +| Events received | `ui:group/member-added`, `ui:group/member-kicked`, `ui:group/member-banned`, `ui:group/member-scope-changed`, `ui:group/ownership-changed` — keeps the member list in sync — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Group membership changes (joins, leaves, kicks, bans, scope changes) — handled internally | +| Full props | See [Props](#props) | + ## Overview @@ -281,7 +181,7 @@ This component does not emit any UI events directly. Kick, ban, and scope change ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how these `ui:group/member-*` and `ui:group/ownership-changed` events are published. | Event | Payload | Behavior | | --- | --- | --- | @@ -694,6 +594,10 @@ View slot props (`headerView`, `loadingView`, `emptyView`, `errorView`, `itemVie | Type | `CometChat.Group` | | Default | — | + +`group` is required — the component renders nothing without it. Obtain the `CometChat.Group` from the selected item in `CometChatGroups` (`onItemClick`), from `CometChat.getGroup(guid)`, or from your own state, then pass it in. See the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) for how the group flows from selection into the members panel. + + --- ### groupMemberRequestBuilder @@ -835,6 +739,10 @@ Function that returns context menu options for each member item (shown on hover/ /> ``` + +These `onClick` handlers are placeholders — the component only renders the menu items; you must implement the behavior. For the "Message Privately" option, open a one-on-one chat with the selected member as shown in the [Message Privately guide](/ui-kit/react/guide-message-privately). Kick, ban, and scope-change actions are handled by the component's built-in options unless you override them here. + + --- ### onItemClick @@ -890,6 +798,10 @@ Callback when the back button in the header is clicked. | Type | `() => void` | | Default | `undefined` | + +`onBack` is a placeholder — the component only renders the back button and invokes this callback. Navigation and layout wiring (closing the panel, returning to the group chat, updating your router) are your app's responsibility. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows how the members panel is wired into the surrounding layout. + + --- ## CSS Selectors diff --git a/ui-kit/react/components/groups.mdx b/ui-kit/react/components/groups.mdx index c9595f707..6a685b2e3 100644 --- a/ui-kit/react/components/groups.mdx +++ b/ui-kit/react/components/groups.mdx @@ -4,134 +4,20 @@ description: "Searchable, scrollable list of groups with selection support and r --- -```json -{ - "component": "CometChatGroups", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatGroups } from \"@cometchat/chat-uikit-react\";", - "description": "Searchable, scrollable list of groups with selection support and real-time membership updates.", - "cssRootClass": ".cometchat-groups", - "primaryOutput": { - "prop": "onItemClick", - "type": "(group: CometChat.Group) => void" - }, - "props": { - "data": { - "groupsRequestBuilder": { - "type": "CometChat.GroupsRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.GroupsRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeGroup": { - "type": "CometChat.Group", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(group: CometChat.Group) => void", - "onSelect": "(group: CometChat.Group, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void" - }, - "visibility": { - "hideGroupType": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatGroupsSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(group: CometChat.Group) => ReactNode", - "leadingView": "(group: CometChat.Group) => ReactNode", - "titleView": "(group: CometChat.Group) => ReactNode", - "subtitleView": "(group: CometChat.Group) => ReactNode", - "trailingView": "(group: CometChat.Group) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(group: CometChat.Group) => CometChatGroupOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:group/created", - "payload": "{ group: CometChat.Group }", - "description": "Adds the new group to the list" - }, - { - "name": "ui:group/deleted", - "payload": "{ group: CometChat.Group }", - "description": "Removes the group from the list" - }, - { - "name": "ui:group/left", - "payload": "{ group: CometChat.Group }", - "description": "Removes (private) or updates (public) the group" - }, - { - "name": "ui:group/member-joined", - "payload": "{ joinedGroup: CometChat.Group }", - "description": "Updates the group (member count)" - }, - { - "name": "ui:group/member-added", - "payload": "{ group: CometChat.Group, members: CometChat.User[], messages: CometChat.BaseMessage[] }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group: CometChat.Group, user: CometChat.User, message: CometChat.BaseMessage }", - "description": "Updates the group" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group: CometChat.Group, user: CometChat.User, newScope: string }", - "description": "Updates the group" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates the group" - } - ], - "sdkListeners": [ - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup" - ], - "types": { - "CometChatGroupOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(group: CometChat.Group) => void" - }, - "CometChatGroupsSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatGroups` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatGroups } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-groups` | +| Primary output | `onItemClick: (group: CometChat.Group) => void` — emits the selected group to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Emits the selected group; wire `onItemClick` to open it (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | +| Events received | `ui:group/created`, `ui:group/deleted`, `ui:group/left`, and `ui:group/member-*` / `ui:group/ownership-changed` — keeps the list in sync — see the [Event System](/ui-kit/react/event-system#user--group-actions) | +| SDK listeners (automatic) | Group membership changes — handled internally | +| Full props | See [Props](#props) | + ## Overview @@ -202,6 +88,8 @@ function GroupList() { ### Full Layout Example +`onItemClick` is where you capture the selected group and mount the chat panel to open the group chat — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the two-panel wiring and the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) for join/details flows. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -289,7 +177,7 @@ This component does not emit any UI events. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how these `ui:group/*` events are published. | Event | Payload | Behavior | | --- | --- | --- | @@ -715,6 +603,10 @@ Function that returns context menu options for each group item (shown on hover/s /> ``` + +The `onClick` handlers above (`leaveGroup`, `openGroupDetails`) are placeholders — the component only renders the menu items; you must implement the actual behavior. The [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) shows the join, leave, and group-details flows end to end. + + --- ### onItemClick diff --git a/ui-kit/react/components/image-bubble.mdx b/ui-kit/react/components/image-bubble.mdx index 1a2508976..d9772d202 100644 --- a/ui-kit/react/components/image-bubble.mdx +++ b/ui-kit/react/components/image-bubble.mdx @@ -5,27 +5,18 @@ description: "A batch-aware bubble that renders one or more image attachments wi --- -```json -{ - "component": "CometChatImagesBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatImagesBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware image bubble. Extracts image attachments and caption from a MediaMessage; renders adaptive grid layouts (single, 2-col, 2x2, overflow) and opens a fullscreen gallery viewer.", - "cssRootClass": ".cometchat-images-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "placeholderImage": { "type": "string" }, - "onImageClicked": { "type": "(attachment, index) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatImagesBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatImagesBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-images-bubble` | +| Primary output | `onImageClicked(attachment, index)` — opens the fullscreen gallery | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/incoming-call.mdx b/ui-kit/react/components/incoming-call.mdx index 31ae55f5d..b503247fc 100644 --- a/ui-kit/react/components/incoming-call.mdx +++ b/ui-kit/react/components/incoming-call.mdx @@ -4,71 +4,20 @@ description: "Displays an incoming call notification with caller info, accept/de --- -```json -{ - "component": "CometChatIncomingCall", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatIncomingCall } from \"@cometchat/chat-uikit-react\";", - "description": "Displays an incoming call notification with caller info, accept/decline buttons, and transitions to the ongoing call screen.", - "cssRootClass": ".cometchat-incoming-call", - "primaryOutput": { - "prop": "onAccept", - "type": "(call: CometChat.Call) => void" - }, - "props": { - "callbacks": { - "onAccept": "(call: CometChat.Call) => void", - "onDecline": "(call: CometChat.Call) => void", - "onCallEnded": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "sound": { - "disableSoundForCalls": { "type": "boolean", "default": false }, - "customSoundForCalls": { "type": "string", "default": "built-in" } - }, - "configuration": { - "callSettingsBuilder": { - "type": "(call: CometChat.Call) => any", - "default": "undefined", - "note": "Custom call settings for the ongoing call session after accepting" - } - }, - "viewSlots": { - "itemView": "(call: CometChat.Call) => ReactNode", - "leadingView": "(call: CometChat.Call) => ReactNode", - "titleView": "(call: CometChat.Call) => ReactNode", - "subtitleView": "(call: CometChat.Call) => ReactNode", - "trailingView": "(call: CometChat.Call) => ReactNode" - } - }, - "events": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Call declined by user" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Ongoing call ended" - } - ], - "sdkListeners": [ - "onIncomingCallReceived", - "onIncomingCallCancelled", - "onOutgoingCallAccepted", - "onOutgoingCallRejected" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined" - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatIncomingCall` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-incoming-call` | +| **Primary output** | `onAccept: (call: CometChat.Call) => void` — fires when the call is accepted | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Mount at the app root to catch incoming calls; wire `onAccept` / `onDecline` | +| **Events emitted** | `ui:call/rejected`, `ui:call/ended` — see [Event System](/ui-kit/react/event-system) | +| **SDK listeners (automatic)** | Incoming and outgoing call lifecycle — handled internally | +| **Full props** | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/message-bubble.mdx b/ui-kit/react/components/message-bubble.mdx index ff35e8223..5cbc22f43 100644 --- a/ui-kit/react/components/message-bubble.mdx +++ b/ui-kit/react/components/message-bubble.mdx @@ -4,61 +4,18 @@ description: "A shared wrapper component that renders all message types with com --- -```json -{ - "component": "CometChatMessageBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Layout shell that wraps plugin-rendered bubble content with shared chrome — avatar, sender name, bubble background, timestamp, receipts, thread replies, reactions, and context menu.", - "cssRootClass": ".cometchat-message-bubble", - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "required": true }, - "alignment": { "type": "'left' | 'right' | 'center'", "required": true }, - "contentView": { "type": "ReactNode", "required": true, "note": "Inner content from the plugin's renderBubble()." }, - "group": { "type": "CometChat.Group" }, - "options": { "type": "CometChatMessageOption[]" }, - "quickOptionsCount": { "type": "number", "default": 2 } - }, - "visibility": { - "hideAvatar": { "type": "boolean", "default": false }, - "forceShowAvatar": { "type": "boolean", "default": false }, - "hideSenderName": { "type": "boolean", "default": false }, - "hideTimestamp": { "type": "boolean", "default": false }, - "hideThreadView": { "type": "boolean", "default": false }, - "hideReceipts": { "type": "boolean", "note": "Reads from GlobalConfig if not set." }, - "showError": { "type": "boolean", "default": false }, - "disableInteraction": { "type": "boolean", "default": false } - }, - "config": { - "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "isSelected": { "type": "boolean" }, - "ariaPosinset": { "type": "number" }, - "ariaSetsize": { "type": "number" }, - "className": { "type": "string" }, - "setRef": { "type": "Ref" }, - "includeBottomViewHeight": { "type": "boolean", "default": false }, - "toggleOptionsVisibility": { "type": "boolean" } - }, - "viewSlots": { - "leadingView": "((message) => ReactNode) | null", - "headerView": "((message) => ReactNode) | null", - "statusInfoView": "((message) => ReactNode) | null", - "footerView": "((message) => ReactNode) | null", - "threadView": "((message) => ReactNode) | null", - "replyView": "ReactNode | null", - "bottomView": "((message) => ReactNode) | null" - }, - "callbacks": { - "onAvatarClick": "(user: CometChat.User) => void", - "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void", - "onOptionClick": "(option: CometChatMessageOption, message: CometChat.BaseMessage) => void", - "onReactionChipClick": "(messageId: number, emoji: string) => void", - "onReactorClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatMessageBubble` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatMessageBubble } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-message-bubble` | +| **Primary output** | None — renders from the SDK message (it renders provided content; there is no single primary callback). | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user. | +| **Stitching** | Feed `message`, `alignment`, and a plugin-rendered `contentView`; it supplies the surrounding chrome. | +| **Full props** | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/message-composer.mdx b/ui-kit/react/components/message-composer.mdx index 6cb59d304..67f436ceb 100644 --- a/ui-kit/react/components/message-composer.mdx +++ b/ui-kit/react/components/message-composer.mdx @@ -4,133 +4,21 @@ description: "Rich text input with attachments, emoji, voice recording, mentions --- -```json -{ - "component": "CometChatMessageComposer", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageComposer } from \"@cometchat/chat-uikit-react\";", - "description": "Rich text input with attachments, emoji, voice recording, mentions, and formatting for sending messages.", - "cssRootClass": ".cometchat-message-composer", - "primaryOutput": { - "prop": "onSendButtonClick", - "type": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void" - }, - "props": { - "entity": { - "user": { "type": "CometChat.User", "default": "undefined" }, - "group": { "type": "CometChat.Group", "default": "undefined" }, - "parentMessageId": { "type": "number", "default": "undefined" } - }, - "layout": { - "layout": { - "type": "CometChatMessageComposerLayout", - "values": ["'compact'", "'multiline'"], - "default": "'compact'" - } - }, - "textInput": { - "initialText": { "type": "string", "default": "undefined" }, - "text": { "type": "string", "default": "undefined", "note": "Controlled mode — consumer owns state" }, - "placeholder": { "type": "string", "default": "'Type a message...'" }, - "enterKeyBehavior": { - "type": "'send' | 'newline' | 'none'", - "default": "'send'" - }, - "maxInputHeight": { "type": "number", "default": "200" } - }, - "richText": { - "enableRichTextEditor": { "type": "boolean", "default": false }, - "hideRichTextFormattingOptions": { "type": "boolean", "default": false }, - "showBubbleMenuOnSelection": { "type": "boolean", "default": false } - }, - "editReply": { - "messageToEdit": { "type": "CometChat.TextMessage | null", "default": "null" }, - "messageToReply": { "type": "CometChat.BaseMessage | null", "default": "null" } - }, - "attachments": { - "attachmentOptions": { "type": "CometChatComposerAttachmentOption[]", "default": "undefined" }, - "hideAttachmentOptions": { "type": "CometChatAttachmentHideOptions", "default": "undefined" }, - "showAttachmentPreview": { "type": "boolean", "default": true }, - "enableMultipleAttachments": { "type": "boolean", "default": true, "note": "Enable multi-attachment staging tray and batch send. Set false for legacy single-select behavior." }, - "disableDragAndDrop": { "type": "boolean", "default": false, "note": "Disable drag-and-drop file upload." }, - "allowedFileTypes": { "type": "string[]", "default": "undefined" } - }, - "hideButtons": { - "hideAttachmentButton": { "type": "boolean", "default": false }, - "hideEmojiKeyboardButton": { "type": "boolean", "default": false }, - "hideVoiceRecordingButton": { "type": "boolean", "default": false }, - "hideStickersButton": { "type": "boolean", "default": false }, - "hideAIButton": { "type": "boolean", "default": true }, - "hideLiveReaction": { "type": "boolean", "default": false }, - "hideSendButton": { "type": "boolean", "default": false }, - "hideError": { "type": "boolean", "default": false } - }, - "mentions": { - "textFormatters": { "type": "CometChatTextFormatter[]", "default": "undefined" }, - "disableMentions": { "type": "boolean", "default": false }, - "disableMentionAll": { "type": "boolean", "default": false }, - "mentionAllLabel": { "type": "string", "default": "'all'" }, - "mentionsUsersRequestBuilder": { "type": "CometChat.UsersRequestBuilder", "default": "undefined" }, - "mentionsGroupMembersRequestBuilder": { "type": "CometChat.GroupMembersRequestBuilder", "default": "undefined" } - }, - "sound": { - "disableTypingEvents": { "type": "boolean", "default": false }, - "disableSoundForMessage": { "type": "boolean", "default": false }, - "customSoundForMessage": { "type": "string", "default": "undefined" } - }, - "misc": { - "disableAutoFocusOnMobile": { "type": "boolean", "default": true }, - "liveReactionIcon": { "type": "string", "default": "undefined" }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "customViews": { - "attachmentButtonIconView": "ReactNode", - "voiceRecordingButtonIconView": "ReactNode", - "emojiButtonIconView": "ReactNode", - "sendButtonView": "ReactNode", - "auxiliaryButtonView": "ReactNode", - "headerView": "ReactNode" - }, - "callbacks": { - "onTextChange": "(text: string) => void", - "onSendButtonClick": "(message: CometChat.BaseMessage, mode?: 'send' | 'edit') => void", - "sendTextMessageOverride": "(text: string, richTextHtml?: string) => string", - "onError": "(error: unknown) => void", - "onClosePreview": "() => void", - "onAttachmentAdded": "(file: File) => void", - "onAttachmentRemoved": "(file: File) => void", - "onMentionSelected": "(user: CometChat.User | CometChat.GroupMember) => void" - } - }, - "events": { - "emitted": [ - { "name": "ui:message/sent", "payload": "{ message, status }", "description": "Message sent (inprogress → success/error)" }, - { "name": "ui:compose/edit", "payload": "{ message, status }", "description": "Message edit (inprogress → success/error/cancelled)" }, - { "name": "ui:compose/reply", "payload": "{ message, status }", "description": "Reply context set/cleared" }, - { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Voice recording started (stops other instances)" } - ], - "received": [ - { "name": "ui:compose/edit", "payload": "{ message, status: 'inprogress' }", "description": "Enters edit mode for the message" }, - { "name": "ui:compose/reply", "payload": "{ message, status: 'inprogress' }", "description": "Sets reply-to message" }, - { "name": "ui:compose/text", "payload": "{ text }", "description": "Sets the composer text programmatically" }, - { "name": "ui:compose/recording-started", "payload": "{ composerInstanceId }", "description": "Stops own recording if another instance started" } - ] - }, - "sdkListeners": [], - "types": { - "CometChatMessageComposerLayout": "'compact' | 'multiline'", - "CometChatAttachmentHideOptions": { - "image": "boolean | undefined", - "video": "boolean | undefined", - "audio": "boolean | undefined", - "file": "boolean | undefined", - "polls": "boolean | undefined", - "collaborativeDocument": "boolean | undefined", - "collaborativeWhiteboard": "boolean | undefined" - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageComposer` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageComposer } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-composer` | +| Primary output | `onSendButtonClick: (message: CometChat.BaseMessage, mode?: 'send' \| 'edit') => void` — emits the sent/edited message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; the AI-assist button requires [AI features](/ui-kit/react/ai-features) enabled in the Dashboard | +| Stitching | Pass `user`, `group`, or `parentMessageId`; the composer sends via the SDK and emits `onSendButtonClick` | +| Events emitted | `ui:message/sent`, `ui:compose/edit`, `ui:compose/reply`, `ui:compose/recording-started` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:compose/edit`, `ui:compose/reply`, `ui:compose/text`, `ui:compose/recording-started` (drives edit/reply/text mode) | +| SDK listeners (automatic) | None; emits typing-indicator events via the SDK when `disableTypingEvents` is `false` | +| Full props | See [Props](#props) | + ## Overview @@ -293,6 +181,10 @@ This mirrors the underlying SDK upload semantics: **failed** uploads are transie - **Count** — a single batch can hold up to a configurable maximum (default **10**, from the `file.count.max` app setting, resolved at runtime). The limit is **all-or-nothing**: if a pick would push the tray past the maximum, the **entire new selection is rejected** — nothing is staged — and a validation banner is shown. The composer does **not** partially accept a subset of files to fill the remaining slots. - **Per-file size** — a file larger than the allowed size (`file.size.max`) is rejected as an individual tile. + +These limits are **Dashboard/app-level settings**, not UI Kit props. The maximum file **count** (`file.count.max`) and **size** (`file.size.max`) are read from your CometChat app settings at runtime, and permitted file **types** are governed by your app's role-based file-type permissions (RBAC/SBAC). If an attachment is rejected unexpectedly, verify these settings for your app and role in the CometChat Dashboard — they are not overridable from the composer. + + ### Why a file is rejected A rejected tile explains itself on hover via a tooltip: @@ -343,7 +235,7 @@ UI events this component publishes: ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system#composer-commands). Publishing `ui:compose/edit` or `ui:compose/reply` (e.g. from the [Message List](/ui-kit/react/components/message-list) edit/reply actions) is how another component drives this composer into edit/reply mode without prop drilling: | Event | Payload | Behavior | | --- | --- | --- | @@ -410,6 +302,10 @@ function ComposerCustomAttachments({ chatUser }: { chatUser: CometChat.User }) { } ``` + +Each custom option's `onClick` is a handler **you** implement — the composer only renders the menu. To send a message from a custom option, use the CometChat SDK or the UI Kit's [Event System](/ui-kit/react/event-system) (e.g. optimistic-send flows). Custom attachment options can also be provided by a [plugin](/ui-kit/react/plugins/overview); `sendTextMessageOverride` similarly lets you intercept the outgoing text before send. + + #### auxiliaryButtonView Replace the auxiliary button area. @@ -520,6 +416,10 @@ View slot props (`headerView`, `sendButtonView`, `auxiliaryButtonView`, `attachm ### Entity + +The composer requires exactly one entity — a `user` (1:1) or a `group` — to know where to send messages. Without either prop it has no conversation to post to. For how to derive the active entity from a conversation/user/group selection and mount the composer, see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation). + + --- #### user @@ -694,6 +594,10 @@ Message to reply to (triggers reply mode with preview). ### Attachments + +**Extension-backed attachment options require a Dashboard extension.** The default attachment menu auto-integrates the **Polls**, **Collaborative Document**, **Collaborative Whiteboard**, and **Sticker** options — but each only appears once its extension is enabled in the [CometChat Dashboard](/ui-kit/react/extensions). If an option is missing, enable the extension: [Polls](/fundamentals/polls), [Collaborative Document](/fundamentals/collaborative-document), [Collaborative Whiteboard](/fundamentals/collaborative-whiteboard), [Stickers](/fundamentals/stickers). See [Extensions](/ui-kit/react/extensions) for the full list of extensions the composer auto-integrates. `hideAttachmentOptions` and `hideStickersButton` only control visibility of options that are already enabled. + + --- #### attachmentOptions @@ -817,27 +721,6 @@ Hide the stickers button. --- -#### hideAIButton - -Hide the AI button. - -| | | -| --- | --- | -| Type | `boolean` | -| Default | `true` | - ---- - -#### hideLiveReaction - -Hide the live reaction button. - -| | | -| --- | --- | -| Type | `boolean` | -| Default | `false` | - ---- #### hideSendButton diff --git a/ui-kit/react/components/message-header.mdx b/ui-kit/react/components/message-header.mdx index 5a507f97f..9488ca871 100644 --- a/ui-kit/react/components/message-header.mdx +++ b/ui-kit/react/components/message-header.mdx @@ -4,158 +4,20 @@ description: "Toolbar displaying conversation details with avatar, name, presenc --- -```json -{ - "component": "CometChatMessageHeader", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageHeader } from \"@cometchat/chat-uikit-react\";", - "description": "Toolbar displaying conversation details with avatar, name, presence status, typing indicator, and call buttons.", - "cssRootClass": ".cometchat-message-header", - "primaryOutput": { - "prop": "onItemClick", - "type": "(entity: CometChat.User | CometChat.Group) => void" - }, - "props": { - "data": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "For 1-on-1 conversations. Mutually exclusive with group." - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "For group conversations. Mutually exclusive with user." - }, - "callSettingsBuilder": { - "type": "any", - "default": "GlobalConfig.callSettingsBuilder or built-in default", - "note": "Custom call settings builder for ongoing call sessions." - }, - "lastActiveAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "relative time format" - }, - "summaryGenerationMessageCount": { - "type": "number", - "default": 1000 - } - }, - "callbacks": { - "onBack": "() => void", - "onItemClick": "(entity: CometChat.User | CometChat.Group) => void", - "onSearchOptionClicked": "() => void", - "onSummaryClick": "() => void", - "onVoiceCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onVideoCallClick": "(entity: CometChat.User | CometChat.Group) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideBackButton": { "type": "boolean", "default": false }, - "showSearchOption": { "type": "boolean", "default": true }, - "showConversationSummaryButton": { "type": "boolean", "default": false }, - "enableAutoSummaryGeneration": { "type": "boolean", "default": false }, - "hideVoiceCallButton": { "type": "boolean", "default": false }, - "hideVideoCallButton": { "type": "boolean", "default": false } - }, - "viewSlots": { - "leadingView": "ReactNode", - "titleView": "ReactNode", - "subtitleView": "ReactNode", - "trailingView": "ReactNode", - "auxiliaryButtonView": "ReactNode" - } - }, - "eventsEmitted": [], - "eventsReceived": [ - { - "name": "ui:call/rejected", - "payload": "{ call }", - "description": "Re-enables call buttons after incoming call rejection" - }, - { - "name": "ui:call/ended", - "payload": "{}", - "description": "Resets all call state (re-enables buttons, hides call screens)" - }, - { - "name": "ui:call/join", - "payload": "{ sessionId, isAudioOnly, group }", - "description": "Starts a direct call (user clicked Join on meeting bubble)" - }, - { - "name": "ui:active-chat/changed", - "payload": "{ unreadCount, ... }", - "description": "Auto-triggers summary when unread >= 15 (if enabled)" - }, - { - "name": "ui:group/member-added", - "payload": "{ group, members, messages }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-kicked", - "payload": "{ group, user, message }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-banned", - "payload": "{ group, user, message }", - "description": "Updates group member count" - }, - { - "name": "ui:group/left", - "payload": "{ group }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-joined", - "payload": "{ joinedGroup }", - "description": "Updates group member count" - }, - { - "name": "ui:group/ownership-changed", - "payload": "{ group: CometChat.Group, newOwner: CometChat.User, previousOwnerUid: string }", - "description": "Updates group member count" - }, - { - "name": "ui:group/member-scope-changed", - "payload": "{ group, user, newScope }", - "description": "Updates group member count" - } - ], - "sdkListeners": [ - "onUserOnline", - "onUserOffline", - "onTypingStarted", - "onTypingEnded", - "onGroupMemberJoined", - "onGroupMemberLeft", - "onGroupMemberKicked", - "onGroupMemberBanned", - "onMemberAddedToGroup", - "onIncomingCallReceived", - "onOutgoingCallAccepted", - "onOutgoingCallRejected", - "onIncomingCallCancelled" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageHeader` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageHeader } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-header` | +| Primary output | `onItemClick`: `(entity: CometChat.User \| CometChat.Group) => void` — opens the chat entity's details | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; the summary button requires the [Conversation Summary AI feature](/ui-kit/react/ai-features#conversation-summary) enabled in the Dashboard | +| Stitching | Pass `user` or `group`; wire `onItemClick` (and call/summary callbacks) as needed | +| Events received | `ui:call/*`, `ui:active-chat/changed`, and `ui:group/*` events keep the header in sync — see the [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Presence, typing, group membership, and call listeners attached internally | +| Full props | See [Props](#props) | + ## Overview @@ -302,13 +164,17 @@ function ChatApp() { | `onVideoCallClick` | `(entity: CometChat.User \| CometChat.Group) => void` | User clicks the video call button | | `onError` | `((error: CometChat.CometChatException) => void) \| null` | SDK error occurs | + +These navigation callbacks are placeholders you wire to your app's layout. `onSearchOptionClicked` should open in-conversation search (mount `CometChatSearch` → jump to a result via `goToMessageId`) — see the [Search Messages guide](/ui-kit/react/guide-search-messages). `onItemClick` typically opens a details/info panel, and `onBack` returns to the conversation list; both are handled by your own routing/layout state. + + ### Events Emitted This component does not emit any UI events directly. Call initiation publishes call events internally via the SDK. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system): | Event | Payload | Behavior | | --- | --- | --- | @@ -625,6 +491,10 @@ Whether to show the search button in the header toolbar. Whether to show the AI conversation summary button. + +The Conversation Summary button (`showConversationSummaryButton`, `enableAutoSummaryGeneration`, `onSummaryClick`) requires the **Conversation Summary AI feature to be enabled** for your app in the CometChat Dashboard. When the feature is disabled or not configured, the button will not surface. See [AI Features (Smart Chat)](/ui-kit/react/ai-features#conversation-summary) and [AI User Copilot](/fundamentals/ai-user-copilot/overview). + + | | | | --- | --- | | Type | `boolean` | diff --git a/ui-kit/react/components/message-information.mdx b/ui-kit/react/components/message-information.mdx index 13aafd2e0..23787fc40 100644 --- a/ui-kit/react/components/message-information.mdx +++ b/ui-kit/react/components/message-information.mdx @@ -4,44 +4,18 @@ description: "Displays detailed message information including delivery and read --- -```json -{ - "component": "CometChatMessageInformation", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageInformation } from \"@cometchat/chat-uikit-react\";", - "description": "Displays detailed message information including delivery and read receipts for 1-on-1 and group conversations.", - "cssRootClass": ".cometchat-message-information", - "primaryOutput": { - "prop": "onClose", - "type": "() => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show information for." }, - "messageInfoDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Custom date format for receipt timestamps (read/delivered)." }, - "messageSentAtDateTimeFormat": { "type": "CometChatMessageInformationCalendarObject", "note": "Format for the sent-at timestamp on the message bubble preview." }, - "textFormatters": { "type": "CometChatTextFormatter[]", "note": "Text formatters for the message bubble preview." }, - "showScrollbar": { "type": "boolean", "default": false, "note": "Whether to show the scrollbar in the content area." }, - "className": { "type": "string", "note": "Optional custom className for the root element." } - }, - "callbacks": { - "onClose": { "type": "() => void", "note": "Called when the panel close button is clicked." }, - "onError": { "type": "(error: unknown) => void", "note": "Called when an SDK error occurs." } - }, - "visibility": { - "showScrollbar": { "type": "boolean", "default": "false", "note": "Whether to show the scrollbar in the content area." } - } - }, - "types": { - "CometChatMessageInformationRootProps": "Root provider props", - "CometChatMessageInformationHeaderProps": "Header sub-component props", - "CometChatMessageInformationMessagePreviewProps": "Message preview sub-component props", - "CometChatMessageInformationReceiptListProps": "Receipt list sub-component props", - "CometChatUserReceiptInfo": "Combined user receipt info (user + readAt + deliveredAt)", - "CometChatMessageInformationContextValue": "Context value for sub-components" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageInformation` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageInformation } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-information` | +| Primary output | `onClose: () => void` — closes the information panel | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onClose` to dismiss the panel | +| Full props | See [Props](#props) | + ## Where It Fits diff --git a/ui-kit/react/components/message-list.mdx b/ui-kit/react/components/message-list.mdx index 936115211..d97a40d19 100644 --- a/ui-kit/react/components/message-list.mdx +++ b/ui-kit/react/components/message-list.mdx @@ -4,207 +4,21 @@ description: "Scrollable message feed with plugin-based bubble rendering, reacti --- -```json -{ - "component": "CometChatMessageList", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatMessageList } from \"@cometchat/chat-uikit-react\";", - "description": "Scrollable message feed with plugin-based bubble rendering, reactions, receipts, threads, and real-time updates.", - "cssRootClass": ".cometchat-message-list", - "primaryOutput": { - "prop": "onThreadRepliesClick", - "type": "(message: CometChat.BaseMessage) => void" - }, - "props": { - "entity": { - "user": { - "type": "CometChat.User", - "default": "undefined", - "note": "For 1-on-1 chat. Mutually exclusive with group." - }, - "group": { - "type": "CometChat.Group", - "default": "undefined", - "note": "For group chat. Mutually exclusive with user." - }, - "parentMessageId": { - "type": "number", - "default": "undefined", - "note": "Enables thread mode — fetches replies to this message." - } - }, - "data": { - "messagesRequestBuilder": { - "type": "CometChat.MessagesRequestBuilder", - "default": "SDK default (limit 30)", - "note": "Pass the builder instance, not the result of .build()" - }, - "reactionsRequestBuilder": { - "type": "CometChat.ReactionsRequestBuilder", - "default": "undefined" - }, - "messageTypes": { - "type": "string[]", - "default": "Plugin registry types" - }, - "messageCategories": { - "type": "string[]", - "default": "Plugin registry categories" - }, - "goToMessageId": { - "type": "number", - "default": "undefined", - "note": "Jump to a specific message (e.g., from search or deep link)" - }, - "startFromUnreadMessages": { - "type": "boolean", - "default": false - }, - "loadLastAgentConversation": { - "type": "boolean", - "default": false - } - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideStickyDate": { "type": "boolean", "default": false }, - "hideDateSeparator": { "type": "boolean", "default": false }, - "hideAvatar": { "type": "boolean", "default": false }, - "hideGroupActionMessages": { "type": "boolean", "default": false }, - "hideModerationView": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false }, - "showSmartReplies": { "type": "boolean", "default": false }, - "showConversationStarters": { "type": "boolean", "default": false }, - "showMarkAsUnreadOption": { "type": "boolean", "default": false }, - "disableTruncation": { "type": "boolean", "default": false }, - "isAgentChat": { "type": "boolean", "default": false } - }, - "optionToggles": { - "hideReplyOption": { "type": "boolean", "default": false }, - "hideReplyInThreadOption": { "type": "boolean", "default": false }, - "hideEditMessageOption": { "type": "boolean", "default": false }, - "hideDeleteMessageOption": { "type": "boolean", "default": false }, - "hideCopyMessageOption": { "type": "boolean", "default": false }, - "hideReactionOption": { "type": "boolean", "default": false }, - "hideMessageInfoOption": { "type": "boolean", "default": false }, - "hideFlagMessageOption": { "type": "boolean", "default": false }, - "hideMessagePrivatelyOption": { "type": "boolean", "default": false }, - "hideTranslateMessageOption": { "type": "boolean", "default": false }, - "hideFlagRemarkField": { "type": "boolean", "default": false }, - "quickOptionsCount": { "type": "number", "default": 3 } - }, - "dateFormatting": { - "separatorDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "stickyDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "messageSentAtDateTimeFormat": { "type": "CometChatDateFormatConfig" }, - "messageInfoDateTimeFormat": { "type": "CometChatDateFormatConfig" } - }, - "alignment": { - "messageAlignment": { - "type": "CometChatMessageListAlignment", - "values": ["0 (left)", "1 (standard)"], - "default": "1 (standard)" - } - }, - "sound": { - "disableSoundForMessages": { "type": "boolean", "default": false }, - "customSoundForMessages": { "type": "string", "default": "built-in" } - }, - "ai": { - "smartRepliesKeywords": { - "type": "string[]", - "default": "['what','when','why','who','where','how','?']" - }, - "smartRepliesDelayDuration": { - "type": "number", - "default": 10000 - } - }, - "callbacks": { - "onThreadRepliesClick": "(message: CometChat.BaseMessage) => void", - "onAvatarClick": "(user: CometChat.User) => void", - "onEditMessage": "(message: CometChat.BaseMessage) => void", - "onReplyMessage": "(message: CometChat.BaseMessage) => void", - "onReactionClick": "(reaction: CometChat.ReactionCount, message: CometChat.BaseMessage) => void", - "onReactionListItemClick": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void", - "onActiveChatChanged": "(data: { user?, group?, message?, unreadMessageCount? }) => void", - "onMessageRead": "(message: CometChat.BaseMessage) => void", - "onMessageDeleted": "(message: CometChat.BaseMessage) => void", - "onConversationMarkedAsRead": "(conversation: CometChat.Conversation) => void", - "onConversationUpdated": "(conversation: CometChat.Conversation) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "viewSlots": { - "bubbleView": "(message: CometChat.BaseMessage, loggedInUser: CometChat.User) => ReactNode", - "headerView": "ReactNode", - "footerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode" - } - }, - "events": [ - { - "name": "ui:message/read", - "payload": "{ message }", - "description": "Message marked as read" - }, - { - "name": "ui:message/deleted", - "payload": "{ message }", - "description": "Message deleted by user" - }, - { - "name": "ui:active-chat/changed", - "payload": "{ user?, group?, message?, unreadMessageCount? }", - "description": "Active chat context changed on init" - }, - { - "name": "ui:conversation/read", - "payload": "{ conversationId }", - "description": "Conversation marked as read" - }, - { - "name": "ui:conversation/updated", - "payload": "{ conversation }", - "description": "Conversation updated (mark-as-unread)" - } - ], - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onTypingStarted", - "onTypingEnded", - "onMessagesDelivered", - "onMessagesRead", - "onMessagesDeliveredToAll", - "onMessagesReadByAll", - "onMessageEdited", - "onMessageDeleted", - "onTransientMessageReceived" - ], - "types": { - "CometChatMessageListAlignment": { - "left": 0, - "standard": 1 - }, - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatMessageList` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatMessageList } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-message-list` | +| Primary output | `onThreadRepliesClick: (message: CometChat.BaseMessage) => void` — opens the message's thread | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; Smart Replies / Conversation Starters require the matching [AI features](/ui-kit/react/ai-features) enabled in the Dashboard | +| Stitching | Pass `user`, `group`, or `parentMessageId`; wire `onThreadRepliesClick` to open a thread | +| Events emitted | `ui:message/read`, `ui:message/deleted`, `ui:active-chat/changed`, `ui:conversation/read`, `ui:conversation/updated` — see [Event System](/ui-kit/react/event-system) | +| Events received | `ui:message/sent`, `ui:compose/edit`, `ui:group/*` member and lifecycle events, `ui:call/*` events — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | Incoming messages, typing, receipts (delivered/read), edits/deletes, transient messages | +| Full props | See [Props](#props) | + ## Overview @@ -420,7 +234,7 @@ Pass a `CometChat.MessagesRequestBuilder` to `messagesRequestBuilder` to control | Prop | Signature | Fires when | | --- | --- | --- | -| `onThreadRepliesClick` | `(message: CometChat.BaseMessage) => void` | User clicks the thread reply indicator | +| `onThreadRepliesClick` | `(message: CometChat.BaseMessage) => void` | User clicks the thread reply indicator — wire this to open a thread panel ([Threaded Messages guide](/ui-kit/react/guide-threaded-messages)) | | `onAvatarClick` | `(user: CometChat.User) => void` | User clicks an avatar on an incoming message | | `onEditMessage` | `(message: CometChat.BaseMessage) => void` | User selects "Edit" from context menu | | `onReplyMessage` | `(message: CometChat.BaseMessage) => void` | User selects "Reply" from context menu | @@ -451,7 +265,7 @@ The "Edit" and "Reply" context menu options publish `ui:compose/edit` and `ui:co ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components) — part of the UI Kit's [Event System](/ui-kit/react/event-system). These let group/call/composer actions elsewhere in your app update the list automatically: | Event | Payload | Behavior | | --- | --- | --- | @@ -684,6 +498,10 @@ View slot props (`bubbleView`, `headerView`, `footerView`, `loadingView`, `empty ### Entity + +The message list requires exactly one entity — a `user` (1:1) or a `group` — to know which conversation to render. Without either prop it shows nothing. For how to derive the active entity from a conversation/user/group selection and mount the list, see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation). + + --- ### user @@ -717,6 +535,10 @@ Enables thread mode. When set, the component fetches and displays replies to the | Type | `number` | | Default | `undefined` | + +Thread replies require wiring: capture the parent from `onThreadRepliesClick`, then mount a **second** `CometChatMessageList` + `CometChatMessageComposer` with this `parentMessageId` (usually alongside a `CometChatThreadHeader`) in a thread panel. See the [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) for the full pattern. + + --- ### Data @@ -776,6 +598,10 @@ Jump to a specific message by ID (e.g., from search results or a deep link). The | Type | `number` | | Default | `undefined` | + +This is how in-conversation search "jump to result" and deep links work: take the message ID from `CometChatSearch` (or your deep link) and pass it here. See the [Search Messages guide](/ui-kit/react/guide-search-messages) for the end-to-end wiring. + + --- ### startFromUnreadMessages @@ -793,6 +619,10 @@ When `true`, the list scrolls to the first unread message on open instead of the When `true`, loads the last agent conversation on initial render. Used for AI agent chat flows. + +Agent chat props (`loadLastAgentConversation`, `isAgentChat`) require an **AI Agent configured in the CometChat Dashboard** — the conversation entity must be that agent user. For a purpose-built agent experience, use the [AI Assistant Chat](/ui-kit/react/components/ai-assistant-chat) component, which wraps this list. See [AI Features](/ui-kit/react/ai-features) for the broader AI capabilities. + + | | | | --- | --- | | Type | `boolean` | @@ -868,6 +698,10 @@ Hide the moderation footer beneath disapproved messages. | Type | `boolean` | | Default | `false` | + +The moderation footer only appears when messages are actually moderated, which requires **Moderation rules configured in the CometChat Dashboard**. See [Moderation overview](/moderation/overview) to set up rules. This prop only controls whether the UI Kit renders the footer for already-moderated messages. + + --- ### showScrollbar @@ -885,6 +719,10 @@ Show the native scrollbar on the message list. When `false`, the scrollbar is hi Show AI-generated smart reply suggestions in the footer when the last received message matches keyword criteria. + +This requires the **Smart Replies** AI feature to be enabled for your app in the CometChat Dashboard. With the feature disabled, no suggestions are generated even when `showSmartReplies` is `true`. See [AI Features](/ui-kit/react/ai-features#smart-replies). + + | | | | --- | --- | | Type | `boolean` | @@ -896,6 +734,10 @@ Show AI-generated smart reply suggestions in the footer when the last received m Show AI-generated conversation starters in the footer when the message list is empty. + +This requires the **Conversation Starter** AI feature to be enabled for your app in the CometChat Dashboard. With the feature disabled, no starters are generated even when `showConversationStarters` is `true`. See [AI Features](/ui-kit/react/ai-features#conversation-starter). + + | | | | --- | --- | | Type | `boolean` | @@ -1026,6 +868,10 @@ Hide the "Flag/Report" option from the message context menu. | Type | `boolean` | | Default | `false` | + +Flagging/reporting a message feeds CometChat **Moderation**. Flagged messages are reviewed in the [Moderation dashboard](/moderation/overview), and custom report reasons are configured there. See [Moderation overview](/moderation/overview). + + --- ### hideMessagePrivatelyOption @@ -1048,6 +894,10 @@ Hide the "Translate" option from the message context menu. | Type | `boolean` | | Default | `false` | + +The "Translate" option only works when the **Message Translation extension is enabled** in the CometChat Dashboard. Without it, the option has nothing to call. Enable it from [Extensions](/ui-kit/react/extensions) — see the [Message Translation guide](/fundamentals/message-translation). + + --- ### hideFlagRemarkField diff --git a/ui-kit/react/components/notification-feed.mdx b/ui-kit/react/components/notification-feed.mdx index 79711463c..fe47845ef 100644 --- a/ui-kit/react/components/notification-feed.mdx +++ b/ui-kit/react/components/notification-feed.mdx @@ -4,61 +4,27 @@ description: "Full-screen notification feed component with category filtering, c --- -```json -{ - "component": "CometChatNotificationFeed", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatNotificationFeed } from \"@cometchat/chat-uikit-react\";", - "description": "Full-screen notification feed with category filtering, timestamp grouping, card rendering via @cometchat/cards-react, real-time updates, and automatic engagement reporting.", - "cssRootClass": ".cometchat-notification-feed", - "props": { - "data": { - "title": { "type": "string", "default": "\"Notifications\"" }, - "notificationFeedRequestBuilder": { "type": "NotificationFeedRequestBuilder", "default": "SDK default (20 per page)" }, - "notificationCategoriesRequestBuilder": { "type": "NotificationCategoriesRequestBuilder", "default": "SDK default (50 per page)" } - }, - "callbacks": { - "onItemClick": "(feedItem: NotificationFeedItem) => void", - "onActionClick": "(feedItem: NotificationFeedItem, action: CardAction) => void", - "onError": "(error: CometChat.CometChatException) => void", - "onBackPress": "() => void" - }, - "visibility": { - "showHeader": { "type": "boolean", "default": true }, - "showBackButton": { "type": "boolean", "default": false }, - "showFilterChips": { "type": "boolean", "default": true } - }, - "viewSlots": { - "headerView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "loadingView": "ReactNode", - "itemView": "(item: NotificationFeedItem) => ReactNode" - }, - "cards": { - "cardThemeMode": { "type": "\"auto\" | \"light\" | \"dark\"", "default": "\"auto\"" }, - "cardThemeOverride": { "type": "Record", "default": "undefined" } - } - }, - "automaticBehaviors": [ - "Real-time updates via WebSocket listener", - "Delivery reporting on fetch", - "Read reporting on viewport visibility (IntersectionObserver)", - "Unread count polling every 30 seconds", - "Infinite scroll pagination", - "Timestamp grouping (Today, Yesterday, day name, date)", - "Category filter chips with unread badges", - "Mark all read button" - ], - "additionalExports": { - "useNotificationUnreadCount": "Hook for tracking unread count with shared polling" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatNotificationFeed` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-notification-feed` | +| Primary output | `onItemClick: (feedItem: NotificationFeedItem) => void` — emits the clicked feed item | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus [Campaigns](/ui-kit/react/campaigns) configured in the Dashboard | +| Stitching | Wire `onItemClick` / `onActionClick` to route the tapped notification (see [Campaigns](/ui-kit/react/campaigns)) | +| SDK listeners (automatic) | Real-time feed updates, delivery/read reporting, and unread-count polling — handled internally | +| Full props | See [Props](#props) | + `CometChatNotificationFeed` displays a scrollable notification feed where each item is rendered as a card using `@cometchat/cards-react`. It handles fetching, pagination, category filtering, timestamp grouping, real-time updates, and read/delivered/engagement reporting automatically. + +**Prerequisite: Campaigns must be configured first.** The feed only shows content once **Campaigns / Notifications are set up in the CometChat Dashboard** — channels, categories, and card templates. Without this, the feed renders but stays empty. See [Campaigns](/ui-kit/react/campaigns) for the end-to-end setup (Dashboard configuration through frontend wiring). + + @@ -200,6 +166,10 @@ Fires when an interactive element (button, link) inside a card is clicked. The ` /> ``` + +**Navigation is your app's responsibility.** `onItemClick` and `onActionClick` only report the intent (deep link, `chatWithUser`, `chatWithGroup`, `openUrl`) — the component does not route anywhere on its own. Your app must handle the transition (open the URL, switch to the chat with `params.uid` / `params.guid`, etc.). For the recommended navigation-event pattern, see [Event System — Navigation](/ui-kit/react/event-system#navigation). + + #### onError Fires when an internal error occurs (network failure, SDK exception). diff --git a/ui-kit/react/components/outgoing-call.mdx b/ui-kit/react/components/outgoing-call.mdx index aee19e4ea..57db7598b 100644 --- a/ui-kit/react/components/outgoing-call.mdx +++ b/ui-kit/react/components/outgoing-call.mdx @@ -4,46 +4,18 @@ description: "Displays the outgoing call screen with receiver info and a cancel --- -```json -{ - "component": "CometChatOutgoingCall", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatOutgoingCall } from \"@cometchat/chat-uikit-react\";", - "description": "Displays the outgoing call screen with receiver info and a cancel button while waiting for the call to be answered.", - "cssRootClass": ".cometchat-outgoing-call", - "primaryOutput": { - "prop": "onCallCanceled", - "type": "() => void" - }, - "props": { - "data": { - "call": { - "type": "CometChat.Call", - "required": true, - "note": "The CometChat call object representing the outgoing call" - } - }, - "callbacks": { - "onCallCanceled": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "sound": { - "disableSoundForCalls": { "type": "boolean", "default": false }, - "customSoundForCalls": { "type": "string", "default": "built-in" } - }, - "viewSlots": { - "titleView": "ReactNode", - "subtitleView": "ReactNode", - "avatarView": "ReactNode", - "cancelButtonView": "ReactNode" - } - }, - "events": [], - "eventsReceived": [], - "sdkListeners": [], - "types": {} -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatOutgoingCall` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatOutgoingCall } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-outgoing-call` | +| Primary output | `onCallCanceled: () => void` — fires when the user cancels the call | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the outgoing `call` object; wire `onCallCanceled` to dismiss the screen | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/poll-bubble.mdx b/ui-kit/react/components/poll-bubble.mdx index 5d0304e1d..f3c371d70 100644 --- a/ui-kit/react/components/poll-bubble.mdx +++ b/ui-kit/react/components/poll-bubble.mdx @@ -5,32 +5,28 @@ description: "A self-extracting bubble that renders a poll with its question, se --- -```json -{ - "component": "CometChatPollBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatPollBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting poll bubble. Derives the question, options, vote counts, totals, and the logged-in user's vote from the message metadata.", - "cssRootClass": ".cometchat-poll-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.CustomMessage", "required": true, "note": "Contains poll data in its metadata; drives all extraction." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "disableInteraction": { "type": "boolean", "default": false }, - "onVoteSubmit": { "type": "(event: CometChatPollVoteEvent) => void" }, - "onVoteError": { "type": "(event: CometChatPollVoteErrorEvent) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatPollBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatPollBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-poll-bubble` | +| Primary output | `onVoteSubmit: (event: CometChatPollVoteEvent) => void` — emits the submitted vote | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Polls extension](/fundamentals/polls) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview `CometChatPollBubble` renders a poll. It is **self-extracting**: pass the SDK custom `message` and the bubble derives the question, options, per-option vote counts, total votes, and the logged-in user's selected option entirely from the message metadata. Selecting an option submits a vote; the bar fills and counts/avatars update. + +**Requires the Polls extension enabled in the [CometChat Dashboard](/fundamentals/polls).** Poll messages (`extension_poll`) are only produced once the Polls extension is turned on for your app. Without it the composer cannot send polls and this bubble never renders. See the [Polls guide](/fundamentals/polls) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes poll messages to this bubble. + + **Live Preview** — interact with the poll bubble. @@ -155,6 +151,9 @@ Additional CSS class applied to the root element. Plugin behavior, context menu, and conversation preview + + Turn on the Polls extension that produces these messages + Render sticker messages diff --git a/ui-kit/react/components/reaction-list.mdx b/ui-kit/react/components/reaction-list.mdx index 26e56de93..60b543f59 100644 --- a/ui-kit/react/components/reaction-list.mdx +++ b/ui-kit/react/components/reaction-list.mdx @@ -4,39 +4,18 @@ description: "Standalone panel showing who reacted to a message, with emoji tab --- -```json -{ - "component": "CometChatReactionList", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatReactionList } from \"@cometchat/chat-uikit-react\";", - "description": "Standalone panel showing who reacted to a message, with emoji tab filtering, pagination, and optimistic removal for the current user.", - "cssRootClass": ".cometchat-reaction-list", - "primaryOutput": { - "prop": "onItemClick", - "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." }, - "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" } - }, - "callbacks": { - "onItemClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void", "note": "Fires only for current user's reactions (to remove)." }, - "onEmpty": { "type": "() => void", "note": "Fires when all reactions are removed. Parent should close the panel." }, - "onError": { "type": "(error: unknown) => void" } - } - }, - "types": { - "CometChatReactionListRootProps": "Root provider props", - "CometChatReactionListTabsProps": "Emoji tab bar props", - "CometChatReactionListItemsProps": "Scrollable reactor list props", - "CometChatReactionListLoadingStateProps": "Shimmer loading state props", - "CometChatReactionListErrorStateProps": "Error state props", - "CometChatReactionListEmptyStateProps": "Empty state props", - "CometChatReactionListContextValue": "Full context value" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatReactionList` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatReactionList } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-reaction-list` | +| Primary output | `onItemClick: (reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void` — removes the current user's reaction | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onEmpty` to close the panel when all reactions are removed | +| Full props | See [Props](#props) | + ## Where It Fits @@ -362,3 +341,18 @@ Optional custom CSS class for the root container. - Shimmer respects `prefers-reduced-motion`. - Spinner respects `prefers-reduced-motion`. - High contrast mode supported via `@media (prefers-contrast: high)`. + +## Related + + +`CometChatReactionList` never calls the SDK itself. The **parent owns reaction removal** — it calls `CometChat.removeReaction`, manages the panel's open/close state, and responds to `onItemClick` (a current-user reaction was tapped) and `onEmpty` (all reactions gone — close the panel). + + + + + Display-only reaction chips shown on message bubbles + + + The parent that owns the reaction add/remove SDK calls + + diff --git a/ui-kit/react/components/reactions.mdx b/ui-kit/react/components/reactions.mdx index 193d56f04..19e345008 100644 --- a/ui-kit/react/components/reactions.mdx +++ b/ui-kit/react/components/reactions.mdx @@ -4,47 +4,28 @@ description: "Displays emoji reaction chips on message bubbles with hover toolti --- -```json -{ - "component": "CometChatReactions", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatReactions } from \"@cometchat/chat-uikit-react\";", - "description": "Displays emoji reaction chips on message bubbles with hover tooltips, a full reactor list, and overflow handling.", - "cssRootClass": ".cometchat-reactions", - "primaryOutput": { - "prop": "onReactionClick", - "type": "(emoji: string, message: CometChat.BaseMessage) => void" - }, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "Required. The message to show reactions for." }, - "alignment": { "type": "'left' | 'right' | 'center'", "default": "'left'" }, - "reactionsRequestBuilder": { "type": "CometChat.ReactionsRequestBuilder" } - }, - "callbacks": { - "onReactionClick": { "type": "(emoji: string, message: CometChat.BaseMessage) => void" }, - "onReactorClick": { "type": "(reaction: CometChat.Reaction, message: CometChat.BaseMessage) => void" }, - "onError": { "type": "(error: unknown) => void" } - }, - "config": { - "hoverDebounceTime": { "type": "number", "note": "Debounce (ms) before showing the hover tooltip." } - } - }, - "types": { - "CometChatReactionsRootProps": "Root provider props", - "CometChatReactionsBarProps": "Reaction chips bar props", - "CometChatReactionsChipProps": "Single reaction chip props", - "CometChatReactionsInfoProps": "Hover tooltip props", - "CometChatReactionsOverflowProps": "Overflow button props" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatReactions` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatReactions } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-reactions` | +| Primary output | `onReactionClick: (emoji: string, message: CometChat.BaseMessage) => void` — emits the clicked reaction | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Pass the target `message`; wire `onReactionClick` / `onReactorClick` to handle taps | +| Full props | See [Props](#props) | + ## Where It Fits `CometChatReactions` renders below message bubbles to show emoji reactions. It is typically used inside `CometChatMessageBubble` as the footer view. The parent (usually `CometChatMessageList`) owns the reaction add/remove SDK calls and passes the updated message down. + +**This component is display-only.** It renders reaction chips and tooltips but does **not** call the SDK to add or remove reactions. The **parent owns all reaction SDK calls** — it handles `onReactionClick` (to toggle a reaction via the SDK), supplies `reactionsRequestBuilder`, and passes an updated `message` prop down after each change. In practice the parent is [Message List](/ui-kit/react/components/message-list), which wires these calls for you. For a standalone reactor panel with removal support, use [Reaction List](/ui-kit/react/components/reaction-list). + + **Live Preview** — interact with the reactions component. diff --git a/ui-kit/react/components/search.mdx b/ui-kit/react/components/search.mdx index fa56f643b..b960c5d7e 100644 --- a/ui-kit/react/components/search.mdx +++ b/ui-kit/react/components/search.mdx @@ -4,138 +4,27 @@ description: "Unified search across conversations and messages with filter chips --- -```json -{ - "component": "CometChatSearch", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatSearch } from \"@cometchat/chat-uikit-react\";", - "description": "Unified search across conversations and messages with filter chips, scoped search, and customizable result views.", - "cssRootClass": ".cometchat-search", - "primaryOutput": { - "prop": "onConversationClicked", - "type": "(event: CometChatSearchConversationClickEvent) => void" - }, - "props": { - "data": { - "searchIn": { - "type": "CometChatSearchScope[]", - "default": "[] (both conversations and messages)", - "note": "Empty array shows both sections" - }, - "searchFilters": { - "type": "CometChatSearchFilter[]", - "default": "all available filters" - }, - "initialSearchFilter": { - "type": "CometChatSearchFilter", - "default": "undefined" - }, - "defaultSearchText": { - "type": "string", - "default": "undefined" - }, - "uid": { - "type": "string", - "default": "undefined", - "note": "Scope search to a specific user's conversation" - }, - "guid": { - "type": "string", - "default": "undefined", - "note": "Scope search to a specific group's conversation" - }, - "lastMessageDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "DD/MM/YYYY for all date ranges in search context" - }, - "messageSentAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - }, - "conversationsRequestBuilder": { - "type": "CometChat.ConversationsRequestBuilder", - "default": "SDK default", - "note": "Pass the builder instance, not the result of .build()" - }, - "messagesRequestBuilder": { - "type": "CometChat.MessagesRequestBuilder", - "default": "SDK default", - "note": "Pass the builder instance, not the result of .build()" - }, - "textFormatters": { - "type": "CometChatTextFormatter[]", - "default": "undefined" - } - }, - "callbacks": { - "onBack": "() => void", - "onConversationClicked": "(event: CometChatSearchConversationClickEvent) => void", - "onMessageClicked": "(event: CometChatSearchMessageClickEvent) => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "visibility": { - "hideBackButton": { "type": "boolean", "default": false }, - "hideUserStatus": { "type": "boolean", "default": false }, - "hideGroupType": { "type": "boolean", "default": false }, - "hideReceipts": { "type": "boolean", "default": false } - }, - "viewSlots": { - "initialView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "conversationItemView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationLeadingView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationTitleView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationSubtitleView": "(conversation: CometChat.Conversation) => ReactNode", - "conversationTrailingView": "(conversation: CometChat.Conversation) => ReactNode", - "messageItemView": "(message: CometChat.BaseMessage) => ReactNode", - "messageLeadingView": "(message: CometChat.BaseMessage) => ReactNode", - "messageTitleView": "(message: CometChat.BaseMessage) => ReactNode", - "messageSubtitleView": "(message: CometChat.BaseMessage) => ReactNode", - "messageTrailingView": "(message: CometChat.BaseMessage) => ReactNode", - "conversationOptions": "(conversation: CometChat.Conversation) => CometChatSearchConversationOption[]" - } - }, - "events": [], - "sdkListeners": [], - "types": { - "CometChatSearchScope": "'conversations' | 'messages'", - "CometChatSearchFilter": "'messages' | 'conversations' | 'unread' | 'groups' | 'photos' | 'videos' | 'links' | 'files' | 'audio'", - "CometChatSearchConversationClickEvent": { - "conversation": "CometChat.Conversation", - "searchKeyword": "string" - }, - "CometChatSearchMessageClickEvent": { - "message": "CometChat.BaseMessage", - "searchKeyword": "string" - }, - "CometChatSearchConversationOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(conversation: CometChat.Conversation) => void" - }, - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatSearch` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatSearch } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-search` | +| **Primary output** | `onConversationClicked: (event: CometChatSearchConversationClickEvent) => void` — emits the clicked search result | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Wire `onConversationClicked` / `onMessageClicked` to open the selected result — see the [Search Messages guide](/ui-kit/react/guide-search-messages) | +| **Full props** | See [Props](#props) | + ## Overview `CometChatSearch` is a unified search component. It searches across conversations and messages, displaying results in separate sections with filter chips for scoping. It emits the selected result via `onConversationClicked` or `onMessageClicked` — both include the `searchKeyword` in the event payload. Wire it to `CometChatConversations` or `CometChatMessageList` to navigate to the matched result. + + +**These result callbacks are required to make the component useful.** `CometChatSearch` does not navigate on its own — clicking a result only fires `onConversationClicked` or `onMessageClicked`. Your app must handle navigation: open the [Conversations](/ui-kit/react/components/conversations) list or route to the matched entity, and pass the message's ID to [Message List](/ui-kit/react/components/message-list) via `goToMessageId` to scroll to the exact message. For an end-to-end walkthrough, see the [Search Messages guide](/ui-kit/react/guide-search-messages). + **Live Preview** — interact with the default search component. diff --git a/ui-kit/react/components/sticker-bubble.mdx b/ui-kit/react/components/sticker-bubble.mdx index 786f159aa..23836999c 100644 --- a/ui-kit/react/components/sticker-bubble.mdx +++ b/ui-kit/react/components/sticker-bubble.mdx @@ -5,29 +5,28 @@ description: "A self-extracting bubble that renders a sticker image from a stick --- -```json -{ - "component": "CometChatStickerBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatStickerBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting sticker bubble. Extracts the sticker image URL and name from the message metadata.", - "cssRootClass": ".cometchat-sticker-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.CustomMessage", "required": true, "note": "The sticker custom message; drives extraction of the image URL and name." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatStickerBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatStickerBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-sticker-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user; plus the [Stickers extension](/fundamentals/stickers) enabled in the Dashboard | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview `CometChatStickerBubble` renders a sticker. It is **self-extracting**: pass the SDK custom `message` and the bubble extracts the sticker image URL and name from its metadata, so it works standalone. + +**Requires the Stickers extension enabled in the [CometChat Dashboard](/fundamentals/stickers).** Sticker messages (`extension_sticker`) are only produced once the Stickers extension is turned on and sticker sets are configured for your app. Without it the composer's sticker keyboard is unavailable and this bubble never renders. See the [Stickers guide](/fundamentals/stickers) to enable it, and the [Plugins overview](/ui-kit/react/plugins/overview#built-in-plugins) for how the UI Kit auto-routes sticker messages to this bubble. + + **Live Preview** — interact with the sticker bubble. @@ -109,6 +108,9 @@ Additional CSS class applied to the root element. Plugin behavior, keyboard, and conversation preview + + Turn on the Stickers extension that produces these messages + Render poll messages diff --git a/ui-kit/react/components/text-bubble.mdx b/ui-kit/react/components/text-bubble.mdx index 2e6b421cb..92f61052a 100644 --- a/ui-kit/react/components/text-bubble.mdx +++ b/ui-kit/react/components/text-bubble.mdx @@ -5,26 +5,18 @@ description: "A self-extracting bubble that renders text messages with markdown, --- -```json -{ - "component": "CometChatTextBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatTextBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Self-extracting text bubble. Renders message text through the formatter pipeline (markdown, mentions, URLs), with optional read-more truncation.", - "cssRootClass": ".cometchat-text-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.BaseMessage", "note": "When set (and text omitted), the bubble extracts content via message.getText() and configures mention formatting." }, - "text": { "type": "string", "note": "Explicit text override (used for media captions). At least one of text / message should be set." }, - "isSentByMe": { "type": "boolean", "default": true }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "disableTruncation": { "type": "boolean", "default": false }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatTextBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatTextBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-text-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/thread-header.mdx b/ui-kit/react/components/thread-header.mdx index c217723ca..e36c22af3 100644 --- a/ui-kit/react/components/thread-header.mdx +++ b/ui-kit/react/components/thread-header.mdx @@ -4,95 +4,20 @@ description: "Displays the parent message bubble and reply count for threaded co --- -```json -{ - "component": "CometChatThreadHeader", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatThreadHeader } from \"@cometchat/chat-uikit-react\";", - "description": "Displays the parent message bubble and reply count for threaded conversations.", - "cssRootClass": ".cometchat-thread-header", - "primaryOutput": { - "prop": "onClose", - "type": "() => void" - }, - "props": { - "data": { - "parentMessage": { - "type": "CometChat.BaseMessage", - "required": true, - "note": "The parent message of the thread" - }, - "separatorDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - }, - "messageSentAtDateTimeFormat": { - "type": "CometChatDateFormatConfig", - "default": "undefined" - } - }, - "visibility": { - "hideReceipts": { "type": "boolean", "default": false }, - "hideDate": { "type": "boolean", "default": false }, - "hideReplyCount": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "callbacks": { - "onClose": "() => void", - "onSubtitleClicked": "() => void", - "onParentDeleted": "() => void", - "onError": "((error: CometChat.CometChatException) => void) | null" - }, - "viewSlots": { - "headerView": "ReactNode", - "messageBubbleView": "ReactNode", - "subtitleView": "ReactNode" - } - }, - "events": { - "emitted": [], - "received": [ - { - "name": "ui:message/sent", - "payload": "{ message, status: 'success' }", - "description": "Increments reply count when current user sends a reply" - }, - { - "name": "ui:compose/edit", - "payload": "{ message, status: 'success' }", - "description": "Updates parent bubble when edited" - }, - { - "name": "ui:message/deleted", - "payload": "{ message }", - "description": "Triggers onParentDeleted" - } - ] - }, - "sdkListeners": [ - "onTextMessageReceived", - "onMediaMessageReceived", - "onCustomMessageReceived", - "onInteractiveMessageReceived", - "onMessageEdited", - "onMessageDeleted" - ], - "types": { - "CometChatDateFormatConfig": { - "today": "string | undefined", - "yesterday": "string | undefined", - "lastWeek": "string | undefined", - "otherDays": "string | undefined", - "relativeTime": { - "minute": "string | undefined", - "minutes": "string | undefined", - "hour": "string | undefined", - "hours": "string | undefined" - } - } - } -} -``` + +| Field | Value | +| --- | --- | +| **Component** | `CometChatThreadHeader` | +| **Package** | `@cometchat/chat-uikit-react` | +| **Import** | `import { CometChatThreadHeader } from "@cometchat/chat-uikit-react";` | +| **CSS root class** | `.cometchat-thread-header` | +| **Primary output** | `onClose` (`() => void`) — closes the thread view | +| **Prerequisites** | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| **Stitching** | Pass the parent `message`; wire `onClose` to dismiss the thread view | +| **Events received** | `ui:message/sent`, `ui:compose/edit`, `ui:message/deleted` — see [Event System](/ui-kit/react/event-system) | +| **SDK listeners (automatic)** | Message updates in the thread — new replies, edits, and deletes to the parent message | +| **Full props** | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/components/users.mdx b/ui-kit/react/components/users.mdx index 44e988e5d..b5410ff44 100644 --- a/ui-kit/react/components/users.mdx +++ b/ui-kit/react/components/users.mdx @@ -4,102 +4,20 @@ description: "Searchable, scrollable list of users with selection support and re --- -```json -{ - "component": "CometChatUsers", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatUsers } from \"@cometchat/chat-uikit-react\";", - "description": "Searchable, scrollable list of users with selection support and real-time presence updates.", - "cssRootClass": ".cometchat-users", - "primaryOutput": { - "prop": "onItemClick", - "type": "(user: CometChat.User) => void" - }, - "props": { - "data": { - "usersRequestBuilder": { - "type": "CometChat.UsersRequestBuilder", - "default": "SDK default (30 per page)", - "note": "Pass the builder instance, not the result of .build()" - }, - "searchRequestBuilder": { - "type": "CometChat.UsersRequestBuilder", - "default": "undefined" - }, - "searchKeyword": { - "type": "string", - "default": "undefined" - }, - "activeUser": { - "type": "CometChat.User", - "default": "undefined" - }, - "sectionHeaderKey": { - "type": "keyof CometChat.User", - "default": "undefined" - } - }, - "callbacks": { - "onItemClick": "(user: CometChat.User) => void", - "onSelect": "(user: CometChat.User, selected: boolean) => void", - "onError": "((error: CometChat.CometChatException) => void) | null", - "onEmpty": "() => void" - }, - "visibility": { - "hideUserStatus": { "type": "boolean", "default": false }, - "hideSearch": { "type": "boolean", "default": false }, - "showSectionHeader": { "type": "boolean", "default": true }, - "showSelectedUsersPreview": { "type": "boolean", "default": false }, - "showScrollbar": { "type": "boolean", "default": false } - }, - "selection": { - "selectionMode": { - "type": "CometChatUsersSelectionMode", - "values": ["'none'", "'single'", "'multiple'"], - "default": "'none'" - } - }, - "viewSlots": { - "itemView": "(user: CometChat.User) => ReactNode", - "leadingView": "(user: CometChat.User) => ReactNode", - "titleView": "(user: CometChat.User) => ReactNode", - "subtitleView": "(user: CometChat.User) => ReactNode", - "trailingView": "(user: CometChat.User) => ReactNode", - "headerView": "ReactNode", - "loadingView": "ReactNode", - "emptyView": "ReactNode", - "errorView": "ReactNode", - "options": "(user: CometChat.User) => CometChatUserOption[]" - } - }, - "events": [], - "eventsReceived": [ - { - "name": "ui:user/blocked", - "payload": "{ user: CometChat.User }", - "description": "Updates user in the list (shows blocked state)" - }, - { - "name": "ui:user/unblocked", - "payload": "{ user: CometChat.User }", - "description": "Updates user in the list (removes blocked state)" - } - ], - "sdkListeners": [ - "onUserOnline", - "onUserOffline" - ], - "types": { - "CometChatUserOption": { - "id": "string", - "title": "string", - "iconURL": "string | undefined", - "onClick": "(user: CometChat.User) => void" - }, - "CometChatUsersSelectionMode": "'none' | 'single' | 'multiple'" - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatUsers` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatUsers } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-users` | +| Primary output | `onItemClick: (user: CometChat.User) => void` — emits the selected user to open | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | Emits the selected user; wire `onItemClick` to open a chat (mount MessageHeader/List/Composer) — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) | +| Events received | `ui:user/blocked`, `ui:user/unblocked` — see [Event System](/ui-kit/react/event-system) | +| SDK listeners (automatic) | User presence (online/offline) | +| Full props | See [Props](#props) | + ## Overview @@ -170,6 +88,8 @@ function UserPicker() { ### New Conversation Example +`onItemClick` is where you capture the selected user and mount the chat panel to start a new conversation — see the [New Chat Creation guide](/ui-kit/react/guide-new-chat-creation) for the complete flow. + ```tsx import { useState } from "react"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @@ -258,7 +178,7 @@ This component does not emit any UI events. ### Events Received -UI events this component subscribes to (published by other components): +UI events this component subscribes to (published by other components). These flow through the shared UI event bus — see [Event System → User & Group Actions](/ui-kit/react/event-system#user--group-actions) for how they are published. To publish these `ui:user/blocked` / `ui:user/unblocked` events yourself when a user is blocked or unblocked, follow the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). | Event | Payload | Behavior | | --- | --- | --- | @@ -763,6 +683,10 @@ Function that returns context menu options for each user item (shown on hover/sw /> ``` + +The `onClick` handlers above (`blockUser`, `openProfile`) are placeholders — the component only renders the menu items; you must implement the actual behavior. For the Block User option, wire it to the SDK and refresh UI state as shown in the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user). + + --- ### onItemClick diff --git a/ui-kit/react/components/video-bubble.mdx b/ui-kit/react/components/video-bubble.mdx index ffe99dc11..2b2961e08 100644 --- a/ui-kit/react/components/video-bubble.mdx +++ b/ui-kit/react/components/video-bubble.mdx @@ -5,26 +5,18 @@ description: "A batch-aware bubble that renders one or more video attachments wi --- -```json -{ - "component": "CometChatVideosBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatVideosBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Batch-aware video bubble. Extracts video attachments and caption from a MediaMessage; renders adaptive grid layouts with poster thumbnails and opens a fullscreen viewer.", - "cssRootClass": ".cometchat-videos-bubble", - "selfExtracting": true, - "multiAttachment": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Drives extraction of attachments and caption." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "onVideoClicked": { "type": "(attachment, index) => void" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatVideosBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatVideosBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-videos-bubble` | +| Primary output | `onVideoClicked: (attachment: CometChatVideosBubbleAttachment, index: number) => void` — opens the fullscreen viewer | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview @@ -40,6 +32,10 @@ Key capabilities: - **Fullscreen viewer** — click any video to open in fullscreen player - **Batch grouping** — rendered as one connected group when several media messages are sent together (handled by the [message list](/ui-kit/react/components/message-list#multi-attachment-batch-grouping)) + +Auto poster thumbnails are produced by the **Thumbnail Generation** extension — enable it in the Dashboard ([Thumbnail Generation](/fundamentals/thumbnail-generation)). Without it, the bubble falls back to the first video frame. + + **Live Preview** — interact with the video bubble. diff --git a/ui-kit/react/components/voice-note-bubble.mdx b/ui-kit/react/components/voice-note-bubble.mdx index 605a34e91..206866e44 100644 --- a/ui-kit/react/components/voice-note-bubble.mdx +++ b/ui-kit/react/components/voice-note-bubble.mdx @@ -5,24 +5,18 @@ description: "A dedicated bubble for recorded voice notes with waveform playback --- -```json -{ - "component": "CometChatVoiceNoteBubble", - "package": "@cometchat/chat-uikit-react", - "import": "import { CometChatVoiceNoteBubble } from \"@cometchat/chat-uikit-react\";", - "description": "Voice note bubble. Renders for audio messages explicitly tagged audioType='voice_note'. Renders the CometChatAudioBubble waveform player internally. Always standalone (no grid).", - "cssRootClass": ".cometchat-audio-bubble", - "selfExtracting": true, - "props": { - "data": { - "message": { "type": "CometChat.MediaMessage", "required": true, "note": "Must have metadata audioType='voice_note'." }, - "alignment": { "type": "\"left\" | \"right\"", "note": "Defaults to sender-vs-logged-in-user." }, - "textFormatters": { "type": "CometChatTextFormatter[]" }, - "className": { "type": "string" } - } - } -} -``` + +| Field | Value | +| --- | --- | +| Component | `CometChatVoiceNoteBubble` | +| Package | `@cometchat/chat-uikit-react` | +| Import | `import { CometChatVoiceNoteBubble } from "@cometchat/chat-uikit-react";` | +| CSS root class | `.cometchat-audio-bubble` | +| Primary output | None — renders from the SDK message | +| Prerequisites | App wrapped in [`CometChatProvider`](/ui-kit/react/cometchat-provider) with valid credentials + a logged-in user | +| Stitching | None — self-extracting from the SDK message | +| Full props | See [Props](#props) | + ## Overview diff --git a/ui-kit/react/core-features.mdx b/ui-kit/react/core-features.mdx index b7b22b315..0567fe8b1 100644 --- a/ui-kit/react/core-features.mdx +++ b/ui-kit/react/core-features.mdx @@ -131,6 +131,10 @@ Mentions is a robust feature provided by CometChat that enhances the interactivi Rich Text Formatting allows users to style their messages with bold, italic, underline, strikethrough, code, links, lists, and blockquotes. This brings richer expression to conversations and helps users emphasize key points, making communication clearer and more engaging. + +Rich text is opt-in: enable it on the composer with `enableRichTextEditor` (see [Message Composer](/ui-kit/react/components/message-composer)). + + @@ -148,9 +152,13 @@ The Threaded Conversations feature enables users to respond directly to a specif + +Threads require wiring: capture the parent message from the Message List's `onThreadRepliesClick`, then mount a second `CometChatMessageList` + `CometChatMessageComposer` (with `parentMessageId`) and a `CometChatThreadHeader` in a thread panel. The [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) walks through the full flow end-to-end. + + | Components | Functionality | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| [Threaded Message Preview](/ui-kit/react/guide-threaded-messages) | [Threaded Message Preview](/ui-kit/react/guide-threaded-messages) component displays the parent message along with the number of replies. | +| [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) | The [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) shows how to build a thread panel: `onThreadRepliesClick`, `parentMessageId`, and `CometChatThreadHeader` (which displays the parent message with its reply count). | ## Quoted Replies @@ -213,6 +221,10 @@ Learn more about how flagged messages are handled, reviewed, and moderated in th Conversation and Advanced Search is a powerful feature provided by CometChat that enables users to quickly find conversations, messages, and media across chats in real time. It supports filters, scopes, and custom actions, allowing users to locate content efficiently while keeping the chat experience smooth and intuitive. + +Search requires wiring the result callbacks to navigation: handle `onConversationClicked` / `onMessageClicked` to open the conversation and jump to a message via the Message List's `goToMessageId`. The [Search Messages guide](/ui-kit/react/guide-search-messages) walks through the full in-conversation search flow. + + diff --git a/ui-kit/react/event-system.mdx b/ui-kit/react/event-system.mdx index a2b35e12e..c73f15c10 100644 --- a/ui-kit/react/event-system.mdx +++ b/ui-kit/react/event-system.mdx @@ -225,6 +225,8 @@ These events are published by UI Kit components for local cross-component commun | `ui:group/member-scope-changed` | `{ message, user, group, newScope }` | GroupMembers | | `ui:group/ownership-changed` | `{ group, newOwner, previousOwnerUid }` | GroupMembers | +**Used by:** the [Block/Unblock User guide](/ui-kit/react/guide-block-unblock-user) publishes and subscribes to `ui:user/blocked` / `ui:user/unblocked` to keep the composer in sync, and the [Group Chat Setup guide](/ui-kit/react/guide-group-chat-setup) reacts to `ui:group/created` in the group creation flow. + ### Thread | Event Type | Payload | Published by | @@ -232,6 +234,8 @@ These events are published by UI Kit components for local cross-component commun | `ui:thread/opened` | `{ parentMessage }` | MessageList (thread option) | | `ui:thread/closed` | — | ThreadHeader | +**Used by:** the [Threaded Messages guide](/ui-kit/react/guide-threaded-messages) opens and closes the thread panel in response to `ui:thread/opened` / `ui:thread/closed`. + ### Call Actions | Event Type | Payload | Published by | @@ -248,6 +252,8 @@ These events are published by UI Kit components for local cross-component commun | --- | --- | --- | | `ui:open-chat` | `{ user?, group? }` | MessageList (message privately option) | +**Used by:** the [Message Privately guide](/ui-kit/react/guide-message-privately) subscribes to `ui:open-chat` to open a private one-on-one panel from within a group chat. + ### Card Actions | Event Type | Payload | Published by | diff --git a/ui-kit/react/guide-block-unblock-user.mdx b/ui-kit/react/guide-block-unblock-user.mdx index 95eb9cb06..7f3a62ce1 100644 --- a/ui-kit/react/guide-block-unblock-user.mdx +++ b/ui-kit/react/guide-block-unblock-user.mdx @@ -105,6 +105,10 @@ const [showBlockDialog, setShowBlockDialog] = useState(false); Use `useCometChatEvents` to subscribe to block/unblock events. This keeps the composer visibility in sync even when the block action originates from a different component (e.g., a details panel). + +The `ui:user/blocked` and `ui:user/unblocked` events are part of the UI Kit's [Event System](/ui-kit/react/event-system#user--group-actions). See that page for the full list of user and group action events and the `usePublishEvent` / `useCometChatEvents` hooks. + + _File: ChatView.tsx_ ```tsx @@ -299,6 +303,7 @@ export default App; ## Next Steps +- [Event System](/ui-kit/react/event-system#user--group-actions) — full reference for the `ui:user/*` events and pub/sub hooks - [Message Composer](/ui-kit/react/components/message-composer) — learn about composer customization - [Conversations](/ui-kit/react/components/conversations) — build a full conversations list - [CometChatProvider](/ui-kit/react/cometchat-provider) — configure the root provider diff --git a/ui-kit/react/guide-group-chat-setup.mdx b/ui-kit/react/guide-group-chat-setup.mdx index ac2667ad9..ec9bccb05 100644 --- a/ui-kit/react/guide-group-chat-setup.mdx +++ b/ui-kit/react/guide-group-chat-setup.mdx @@ -69,6 +69,10 @@ async function createGroup() { } ``` + +When a group is created through the UI Kit's built-in flow, it publishes the `ui:group/created` event on the [Event System](/ui-kit/react/event-system#user--group-actions). Subscribe with `useCometChatEvents` if other components need to react to new groups being created. + + ## Step 3: Add members to the group After creating a group, add members using `CometChat.addMembersToGroup()`. Each member needs a UID and a scope (admin, moderator, or participant). @@ -355,4 +359,5 @@ export default App; - [Groups](/ui-kit/react/components/groups) — browse and join existing groups - [Group Members](/ui-kit/react/components/group-members) — manage group membership - [Message Header](/ui-kit/react/components/message-header) — customize the group header +- [Event System](/ui-kit/react/event-system#user--group-actions) — react to `ui:group/created` and other group action events - [CometChatProvider](/ui-kit/react/cometchat-provider) — configure the root provider diff --git a/ui-kit/react/guide-message-privately.mdx b/ui-kit/react/guide-message-privately.mdx index 02454e238..ae0bf8111 100644 --- a/ui-kit/react/guide-message-privately.mdx +++ b/ui-kit/react/guide-message-privately.mdx @@ -105,6 +105,10 @@ async function handleMessagePrivately(uid: string) { Use `useCometChatEvents` to subscribe to the `ui:open-chat` event, which is published internally when a user clicks "Message Privately" from the context menu. When the event fires, extract the user and open the private panel. + +`ui:open-chat` is one of the UI Kit's [Event System — Navigation events](/ui-kit/react/event-system#navigation). See that page for the event payload and the full list of navigation and UI events. + + ```tsx import { useCometChatEvents } from "@cometchat/chat-uikit-react"; import type { CometChatEvent } from "@cometchat/chat-uikit-react"; @@ -260,6 +264,7 @@ export default App; ## Next Steps +- [Event System](/ui-kit/react/event-system#navigation) — reference for `ui:open-chat` and other navigation events - [Message Composer](/ui-kit/react/components/message-composer) — customize the composer for private chats - [Conversations](/ui-kit/react/components/conversations) — manage the conversations list - [Users](/ui-kit/react/components/users) — browse and select users directly diff --git a/ui-kit/react/guide-threaded-messages.mdx b/ui-kit/react/guide-threaded-messages.mdx index ced528be6..72f48f797 100644 --- a/ui-kit/react/guide-threaded-messages.mdx +++ b/ui-kit/react/guide-threaded-messages.mdx @@ -45,6 +45,10 @@ function ChatWithThreads() { Use the `onThreadRepliesClick` callback on `CometChatMessageList` to capture when a user clicks "Reply in Thread." This sets the threaded message and opens the panel — no events required. + +This guide uses a state-based approach, but the UI Kit also emits `ui:thread/opened` and `ui:thread/closed` on its [Event System — Thread events](/ui-kit/react/event-system#thread). Subscribe to those with `useCometChatEvents` if you need to react to thread open/close from another component. + + _File: ChatWithThreads.tsx_ ```tsx @@ -211,4 +215,5 @@ export default App; - [Thread Header](/ui-kit/react/components/thread-header) — customize the thread header appearance - [Message List](/ui-kit/react/components/message-list) — configure message list rendering and options +- [Event System](/ui-kit/react/event-system#thread) — subscribe to `ui:thread/opened` and `ui:thread/closed` events - [CometChatProvider](/ui-kit/react/cometchat-provider) — learn about provider configuration diff --git a/ui-kit/react/plugins/custom-plugin.mdx b/ui-kit/react/plugins/custom-plugin.mdx index e12959a5f..b74fb5757 100644 --- a/ui-kit/react/plugins/custom-plugin.mdx +++ b/ui-kit/react/plugins/custom-plugin.mdx @@ -121,7 +121,7 @@ function App() { } ``` -Your plugin is appended after the default plugins. Since resolution is first-match, default plugins handle their types first, and your plugin handles `"location"` messages. +Your plugin is prepended before the default plugins. Since resolution is first-match, your plugin takes precedence for the types it declares — here it handles `"location"` messages, a type no default plugin claims. ## Step 3: Send a Location Message @@ -214,10 +214,12 @@ The `context` object passed to every plugin method: | `onFlagMessage` | `(msg) => void` | Open flag/report dialog | | `showToast` | `(text) => void` | Show a toast notification | | `getTextFormatters` | `() => Formatter[]` | Get text formatters for caption rendering | -| `publish` | `(event) => void` | Publish a UI event | +| `publish` | `(event) => void` | Publish a UI event — part of the UI Kit's [Event System](/ui-kit/react/event-system). Use it to drive other components (e.g. navigation, composer commands) from your plugin. | ## Tips +- **External API keys are your responsibility** — the map preview above calls the Google Maps Static API with `key=YOUR_API_KEY`. Replace it with your own Google Maps API key (an external dependency; not provided by CometChat). +- **Use `context.publish`** — to communicate with the rest of the UI, publish [UI events](/ui-kit/react/event-system) rather than reaching into other components directly - **Lazy-load heavy components** — use `React.lazy()` + `Suspense` for bubble components that import large libraries - **Use `context.getLocalizedString`** — for any user-facing text in options or bubbles - **Return `[]` from `getOptions`** — for system messages that shouldn't have a context menu diff --git a/ui-kit/react/plugins/overview.mdx b/ui-kit/react/plugins/overview.mdx index 2d525be49..ba2173257 100644 --- a/ui-kit/react/plugins/overview.mdx +++ b/ui-kit/react/plugins/overview.mdx @@ -73,7 +73,7 @@ Message { type: "image", category: "message" } ## Adding Plugins -All default plugins are always included. To add your own custom plugins, pass them via the `plugins` prop on `CometChatProvider`. They are appended after the defaults, so default plugins keep priority for their message types: +All default plugins are always included. To add your own custom plugins, pass them via the `plugins` prop on `CometChatProvider`. They are **prepended before** the defaults in the registry, so — because resolution is first-match — your custom plugin **takes precedence** over a default plugin that handles the same message type: ```tsx import { CometChatProvider } from "@cometchat/chat-uikit-react"; @@ -92,7 +92,11 @@ function App() { ## Built-in Plugins -These plugins are included automatically — no configuration needed. Each routes its message type to a bubble component; follow the component link for the full rendering behavior, props, and CSS. +These plugins are included automatically — no code configuration needed to render their message type. Each routes its message type to a bubble component; follow the component link for the full rendering behavior, props, and CSS. + + +**Extension-backed plugins require a Dashboard extension.** The renderer for the four extension plugins — **Polls** (`extension_poll`), **Stickers** (`extension_sticker`), **Collaborative Document** (`extension_document`), and **Collaborative Whiteboard** (`extension_whiteboard`) — ships with the UI Kit, but the messages themselves are only produced once the matching extension is enabled in the [CometChat Dashboard](https://app.cometchat.com). Enable each one before the composer can send it or the bubble can appear: [Polls](/fundamentals/polls), [Stickers](/fundamentals/stickers), [Collaborative Document](/fundamentals/collaborative-document), [Collaborative Whiteboard](/fundamentals/collaborative-whiteboard). + | Plugin | Message type(s) | Category | What it renders | Component | | --- | --- | --- | --- | --- | @@ -101,10 +105,10 @@ These plugins are included automatically — no configuration needed. Each route | **Video** | `video` | `message` | Video grid with poster thumbnails, duration overlays, and a fullscreen viewer | [Video Bubble](/ui-kit/react/components/video-bubble) | | **File** | `file` | `message` | Stacked file cards with type icons, size, and download | [File Bubble](/ui-kit/react/components/file-bubble) | | **Audio** | `audio` | `message` | Attached audio as stacked player cards; recorded voice notes as a waveform player | [Audio Bubble](/ui-kit/react/components/audio-bubble) | -| **Polls** | `extension_poll` | `custom` | Interactive poll with voting and live results | [Poll Bubble](/ui-kit/react/components/poll-bubble) | -| **Stickers** | `extension_sticker` | `custom` | Sticker image extracted from the message metadata | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) | -| **Collaborative Document** | `extension_document` | `custom` | Document card with an "Open Document" button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) | -| **Collaborative Whiteboard** | `extension_whiteboard` | `custom` | Whiteboard card with an "Open Whiteboard" button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) | +| **Polls** ([enable in Dashboard](/fundamentals/polls)) | `extension_poll` | `custom` | Interactive poll with voting and live results | [Poll Bubble](/ui-kit/react/components/poll-bubble) | +| **Stickers** ([enable in Dashboard](/fundamentals/stickers)) | `extension_sticker` | `custom` | Sticker image extracted from the message metadata | [Sticker Bubble](/ui-kit/react/components/sticker-bubble) | +| **Collaborative Document** ([enable in Dashboard](/fundamentals/collaborative-document)) | `extension_document` | `custom` | Document card with an "Open Document" button | [Collaborative Document Bubble](/ui-kit/react/components/collaborative-document-bubble) | +| **Collaborative Whiteboard** ([enable in Dashboard](/fundamentals/collaborative-whiteboard)) | `extension_whiteboard` | `custom` | Whiteboard card with an "Open Whiteboard" button | [Collaborative Whiteboard Bubble](/ui-kit/react/components/collaborative-whiteboard-bubble) | | **Card** | any | `card` | Developer-defined card messages, drawn by the `CometChatCardView` renderer | [Card Bubble](/ui-kit/react/components/card-bubble) | | **Group Action** | `groupMember` | `action` | Centered system messages (joined, left, kicked, banned, scope change) | [Group Action Bubble](/ui-kit/react/components/group-action-bubble) | | **Call Action** | `audio` / `video` | `call` | Centered call status messages (missed, outgoing, incoming, ended) | [Call Action Bubble](/ui-kit/react/components/call-action-bubble) | diff --git a/ui-kit/react/plugins/text-formatters.mdx b/ui-kit/react/plugins/text-formatters.mdx index e908319ad..a54434392 100644 --- a/ui-kit/react/plugins/text-formatters.mdx +++ b/ui-kit/react/plugins/text-formatters.mdx @@ -11,14 +11,14 @@ Text formatters detect patterns in message text and transform them into formatte | Formatter | Priority | Detects | Output | | --- | --- | --- | --- | | `CometChatMarkdownFormatter` | 10 | `**bold**`, `_italic_`, `` `code` ``, `> quote`, lists, links | HTML tags (``, ``, ``, etc.) | -| `CometChatMentionsFormatter` | 50 | `<@uid:xxx>` tokens | Styled `@DisplayName` chips | +| `CometChatMentionsFormatter` | 20 | `<@uid:xxx>` tokens | Styled `@DisplayName` chips | | `CometChatUrlFormatter` | 100 | `https://...`, `www.` | Clickable `` links | ``` Raw text: "Hey **@Alice**, check https://example.com" ↓ MarkdownFormatter (priority 10) "Hey @Alice, check https://example.com" - ↓ MentionsFormatter (priority 50) + ↓ MentionsFormatter (priority 20) "Hey @Alice, check https://example.com" ↓ UrlFormatter (priority 100) "Hey @Alice, check https://example.com" @@ -59,7 +59,7 @@ import { CometChatTextFormatter } from "@cometchat/chat-uikit-react"; export class HashtagFormatter extends CometChatTextFormatter { readonly id = "hashtag-formatter"; - override priority = 90; // After mentions (50), before URLs (100) + override priority = 90; // After mentions (20), before URLs (100) private hashtags: string[] = []; @@ -101,6 +101,8 @@ export class HashtagFormatter extends CometChatTextFormatter { ## Registering Custom Formatters +A custom formatter is not registered on its own — it must be wrapped in a custom **text plugin** (see [Plugins overview](/ui-kit/react/plugins/overview)) and that plugin registered via the provider's `plugins` prop (see [With Additional Plugins](/ui-kit/react/cometchat-provider#with-additional-plugins)). + Custom formatters are registered by creating a custom text plugin that provides them: ```typescript title="src/plugins/CustomTextPlugin.ts" @@ -120,7 +122,7 @@ export const CustomTextPlugin = { getTextFormatters(): CometChatTextFormatter[] { return [ new CometChatMarkdownFormatter(), // priority 10 - new CometChatMentionsFormatter(), // priority 50 + new CometChatMentionsFormatter(), // priority 20 new HashtagFormatter(), // priority 90 new CometChatUrlFormatter(), // priority 100 ];