cometchat-customization

Ground truth: the per-platform UI Kit customization systems (theme objects / CSS vars, message templates, text formatters) verified against the installed kit. (Official docs linked below.) Verify symbols against the installed package/source before relying on them.

Companion skills: cometchat-components provides the component catalog (what exists); this skill provides the customization workflow (how to modify what exists). Use cometchat-components to look up component names and props, then use this skill to plan and execute the customization. For any pattern not covered below, the docs MCP at cometchat-docs is the source of truth — query it before generating any code.

Use this skill when

The user has already run /cometchat (or invoked the cometchat skill via their agent's mechanism — keyword "cometchat" or "integrate chat" works in most agents) (Phase A complete — there's a working integration with .cometchat/state.json) and wants to change how a component looks or behaves beyond what the CLI's deterministic commands handle.

Trigger phrases:

• "customize the message list"
• "filter the conversations to only show X"
• "change the message bubble color/shape/layout"
• "add a custom header above the chat"
• "subscribe to message-received events"
• "show a custom loading state"
• "add a custom action to the message options menu"
• "I want to inject my own UI into CometChatX"
• /cometchat customize

Do not use this skill when

• The user wants to enable a packaged feature (calls, polls, AI smart replies, etc.) → use cometchat-features instead
• The user wants to change theme tokens (primary color, font, border radius) → use cometchat-theming instead (CSS-variable overrides written directly into the project — there is no theming CLI)
• The user wants to start a new integration → use the cometchat dispatcher skill to run Phase A first
• The user wants to fix something broken → use cometchat-troubleshooting and run cometchat doctor

Docs MCP contract

This skill is fundamentally docs-driven — every customization question requires a fact (prop name, callback signature, builder method, event topic, CSS selector) that lives in the canonical CometChat docs, not in this skill's text. Embedding examples here would create drift the moment the SDK changes.

The canonical CometChat docs are the source of truth for this skill. The docs MCP at cometchat-docs is the best way to query them when available, but it is not a hard requirement — fall back to the public docs site for any agent without it. The docs cover:

• Component prop tables (every component, every prop, every default)
• Custom view slots: headerView, subtitleView, tailView, optionsView, bubbleView, emptyView, loadingView, errorView (which components support which slots — verified against the v6 React kit: the list components CometChatConversations/MessageList/Users/ Groups use emptyView/loadingView/errorView, not the *StateView form; only CometChatNotificationFeed uses emptyStateView/loadingStateView/errorStateView)
• Message template overrides (CometChatMessageTemplate.type, category, contentView, headerView, footerView)
• Request builders for filtering data: ConversationsRequestBuilder, MessagesRequestBuilder, UsersRequestBuilder, GroupsRequestBuilder, CallLogsRequestBuilder and their methods
• SDK events: CometChatMessageEvents, CometChatUserEvents, CometChatGroupEvents, CometChatCallEvents, CometChatUIEvents and the topic names
• CSS selectors for component-level styling overrides (.cometchat-message-bubble-incoming, .cometchat-conversations-header, etc.)

Hard rules:

1. Look up the docs before generating any customization code. Never invent prop names, builder methods, event topics, or CSS classes from training-data memory. Use whichever lookup path is available, in order:
   • (a) docs MCP — query the cometchat-docs MCP tool if your agent has it. Richest path.
   • (b) install the MCP, if your agent supports it — Claude Code: claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp. Other agents (Cursor, Codex, Cline, …) configure MCP their own way, or not at all — do NOT block.
   • (c) fetch/search the public docs — same content at the canonical URLs below, or web-search site:cometchat.com/docs. Universal fallback; never STOP and dead-end the user when the MCP isn't installed — fall through to (c).
2. Prefer composition (custom view props) over CSS overrides when both are options — composition is more stable across SDK versions.
3. Canonical reference URLs:
   • Components overview: https://www.cometchat.com/docs/ui-kit/react/components-overview
   • Guides index: https://www.cometchat.com/docs/ui-kit/react/guide-overview — the 7 maintained task recipes (prefer these over hand-rolling): Block/Unblock · Call Log Details · Group Management · Message Privately · New Chat · Search Messages · Threaded Messages
   • Custom message recipes (verified, copy-ready): custom message TYPES, overriding an existing type's bubble (bubbleView/contentView), adding a Message Composer attachment option, and adding a message action like Forward — all live in cometchat-features §Type 5 (append-not-replace via CometChatUIKit.getDataSource()). Route there for the actual code; this skill covers the custom-VIEW-slot props.
   • Theming + styling: https://www.cometchat.com/docs/ui-kit/react/theme
   • Events: https://www.cometchat.com/docs/ui-kit/react/events
   • Methods: https://www.cometchat.com/docs/ui-kit/react/methods
   • Text formatters (inline mention/URL/markdown/custom-token styling — CometChatTextFormatter): the four formatter guides custom-text-formatter-guide, mentions-formatter-guide, url-formatter-guide, shortcut-formatter-guide under ui-kit/react/. Recipe + the append-not-replace getAllTextFormatters({}) pattern live in cometchat-features §Type 5 → Text formatters.
   • Localization (languages, custom strings, date/time formatting): handled by the dedicated cometchat-i18n skill (CometChatLocalize) — route there for any locale/string work; docs https://www.cometchat.com/docs/ui-kit/react/localize

Steps

Step 1 — Verify Phase A is done

npx @cometchat/skills-cli info --json

If integrated is false, stop and tell the user to run /cometchat first to create the base integration. Customization modifies an existing integration; it doesn't create one.

Note the framework, experience, files_owned, and applied_features from the response — you'll need them in the next steps.

Step 2 — Four-tier discovery: existing-component prop, new component, stylesheet, sample app

START HERE: Read the component catalog at references/component-catalog.md (in this skill's directory). It has the canonical list of all 88 exported symbols, all 14 sample-app patterns, and a 40-row task→component lookup table. If the user's request maps to an entry in the catalog, use that entry directly — skip the rest of this step.

If the catalog doesn't have a match (or you need prop-level detail), walk these FOUR discovery checks in this exact order:

1. Existing-component prop check (2a): does a component the integration ALREADY mounts have a prop that does what the user is asking for? The kit follows a "props over components" philosophy — most additions are props on existing components, not new components. This check goes FIRST.
2. New-component check (2b): if 2a turned up nothing, is there a built-in CometChat<X> component in @cometchat/chat-uikit-react's exports?
3. Stylesheet check (2c): is there a --cometchat-<x> CSS variable for any styling you'd write?
4. Sample app check (2d): is there a reference implementation in the sample app at github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app/src/components for the user's pattern?

The CometChat React UI Kit ships FOUR things, not one:

• A "props over components" API where most features (search bar, filters, custom views, click handlers, disable flags) are PROPS on existing components — NOT new components
• 60+ named React components in the npm package
• A 200+ CSS variable system at @cometchat/chat-uikit-react/css-variables.css
• A reference sample app on GitHub with implementations for common chat UX patterns (user/group details, threaded messages layout, top-level home layout, multi-tab chat, notifications, new chat dialog, etc.) that combine multiple kit components but aren't shipped as single named exports

Critical: the docs MCP does NOT index the sample app. When the MCP says "no CometChat<X> component exists", that only covers the npm package — you must still check the sample app via GitHub before concluding the user needs hand-rolled code.

Hand-rolling something the kit, the variable system, OR the sample app already provides means missing the kit's theming, accessibility, i18n, error handling, and every future SDK update.

2a. Existing-component prop check (do this FIRST)

Most chat features are already props on the components you have. A user asking for "add search", "filter conversations", "custom empty state", or "click handler on a message" is almost always asking for a prop, not a new component or custom code.

Process:

1. List the CometChat components currently mounted in the integration. Read the integration's owned files (from state.json) and grep for <CometChat JSX usage:

   grep -hoE '<CometChat[A-Z][a-zA-Z]*' \
     $(jq -r '.files_owned[]' .cometchat/state.json 2>/dev/null) \
     2>/dev/null | sort -u
   

2. Query the docs MCP for the props of each mounted component:
   • "CometChatConversations props"
   • "CometChatMessageList props"
   • "CometChatMessageHeader props"
   • "CometChatMessageComposer props"
3. Look for a prop that maps to the user's intent. Common mappings:

User asks for	Likely prop on which component
Search bar / "add search"	showSearchBar on CometChatConversations (or onSearchBarClicked to swap in <CometChatSearch> for advanced dual-scope search)
Filter conversations	conversationsRequestBuilder on CometChatConversations
Filter messages	messagesRequestBuilder on CometChatMessageList
Filter users / groups	usersRequestBuilder / groupsRequestBuilder
Custom empty state	emptyView on the list components (Conversations/MessageList/Users/Groups); emptyStateView only on CometChatNotificationFeed
Custom error UI	errorView (list components); errorStateView on CometChatNotificationFeed
Custom loading UI	loadingView (list components); loadingStateView on CometChatNotificationFeed
Custom header above the list	headerView
Custom message bubble	templates prop on CometChatMessageList (not a custom bubble component)
Click handler on item / message / search bar / back button	onItemClick, onMessageClick, onBack, onSearchBarClicked
Hide / disable a sub-feature	disable* boolean props (e.g. disableTyping, disableReactions)
Custom subtitle / status / timestamp	subtitleView, statusView, timestampView
Show / hide receipts	hideReceipts
Selection mode	selectionMode on list components

If you find a matching prop, just add the prop and stop. No new components. No custom CSS. No new files. Surface to the user: "The <X> you already have supports this via the <propName> prop. Adding that single prop."

If 2a turns up nothing, proceed to 2b.

2b. New-component check (do this only if 2a turned up nothing)

Common requests that look like "customization" but are actually "use the existing component":

User asks for	Use this built-in component
Threaded replies / "wire up threads"	CometChatThreadHeader + scope a CometChatMessageList and CometChatMessageComposer with parentMessageId
Group members panel / "list group members"	CometChatGroupMembers
Add members to a group	CometChatAddMembers
Transfer group ownership	CometChatTransferOwnership
Banned users management	CometChatBannedMembers
Block/unblock users panel	CometChatBlockedUsers
New chat / "start a new conversation" dialog	CometChatNewChat
Create new group dialog	CometChatCreateGroup
User / group details panel	CometChatDetails
Mentions popover in composer	CometChatMentionsFormatter (already wired into the composer)
Voice / video call buttons in header	CometChatCallButtons
Outgoing call screen	CometChatOutgoingCall
Incoming call notification	CometChatIncomingCall
Ongoing call UI	CometChatOngoingCall
Call logs list	CometChatCallLogs
Reactions on messages	Already built into CometChatMessageList — check if it's just disabled
Message bubble customization	Use the templates prop on CometChatMessageList, not a custom bubble component

⚠️ Not every row above is a kit export. CometChatAddMembers, CometChatTransferOwnership, CometChatBannedMembers, CometChatBlockedUsers, CometChatNewChat, CometChatCreateGroup, and CometChatDetails are sample-app components, NOT @cometchat/chat-uikit-react v6 exports — importing <CometChatTransferOwnership/> etc. is an unresolved-import build error. Build these by copying the sample-app implementation (§2d), do not import them from the package. The genuinely package-exported entries in this table are: CometChatThreadHeader, CometChatGroupMembers, CometChatMentionsFormatter, CometChatCallButtons, CometChatOutgoingCall, CometChatIncomingCall, CometChatOngoingCall, CometChatCallLogs. Always grep the installed package's exports (next step) before emitting any of these.

Search strategies, in this order:

1. Query the docs MCP with the user's intent in plain English. Examples:
   • "thread reply UI react ui kit" → finds CometChatThreadHeader
   • "new chat dialog" → finds CometChatNewChat
   • "group transfer ownership" → finds CometChatTransferOwnership
   • "block user list" → finds CometChatBlockedUsers
2. Grep the user's installed package for matching exports:

   grep -E "^export.*CometChat[A-Z][a-zA-Z]+" \
     node_modules/@cometchat/chat-uikit-react/dist/index.d.ts \
     2>/dev/null | head -50
   

3. Browse the v6 components reference at https://www.cometchat.com/docs/ui-kit/react/components-overview

If you find a built-in component that matches, use it as-is. Surface to the user: "The kit already ships CometChat<X> for this. I'll wire it up directly."

2c. Stylesheet check (do this even when you DO need custom layout glue)

Even when you have to write some CSS for layout glue (positioning a panel, sizing a container, wiring up the height chain that .cometchat-message-list requires), never hand-pick colors, fonts, borders, spacings, or radii from your head. The kit ships a canonical CSS variable system. Use it.

The rule:

• ✅ OK: custom CSS for layout glue (positioning, sizing, flex containers, the height chain). Example: .thread-wrapper { width: 400px; height: 100vh; display: flex; flex-direction: column; }
• ✅ OK: custom CSS that consumes kit variables. Example: .thread-wrapper { border-left: 1px solid var(--cometchat-border-color-light); background: var(--cometchat-background-color-01); }
• ❌ NOT OK: custom CSS for any header / button / icon / panel / badge / divider that the kit already provides as a component. Example: a hand-rolled .thread-header + .thread-close button when CometChatThreadHeader exists.
• ❌ NOT OK: hardcoded colors / fonts / borders / radii / spacings that don't reference the --cometchat-* variables. Example: border: 1px solid #E8E8E8 instead of border: 1px solid var(--cometchat-border-color-light).

Discovery commands for the variable system:

# List every --cometchat-* variable the kit defines
grep -oE '\-\-cometchat-[a-z0-9-]+' \
  node_modules/@cometchat/chat-uikit-react/css-variables.css \
  2>/dev/null | sort -u | head -60

# Or search for a specific token category
grep -E '\-\-cometchat-(border|background|text|primary|font)' \
  node_modules/@cometchat/chat-uikit-react/css-variables.css \
  2>/dev/null | head -40

Common variable categories (query the docs MCP for the canonical list — these change between SDK versions):

Category	Example variables
Brand colors	--cometchat-primary-color, --cometchat-error-color, --cometchat-success-color
Backgrounds	--cometchat-background-color-01 (white), --cometchat-background-color-02, --cometchat-background-color-03 (light grey)
Text	--cometchat-text-color-primary, --cometchat-text-color-secondary, --cometchat-text-color-tertiary
Borders	--cometchat-border-color-light, --cometchat-border-color-default, --cometchat-border-color-dark
Radii	--cometchat-radius-1, --cometchat-radius-2, --cometchat-radius-3, --cometchat-radius-max
Fonts	--cometchat-font-heading1-bold, --cometchat-font-heading4-medium, --cometchat-font-body-regular, --cometchat-font-caption2-regular
Spacing	--cometchat-spacing-1 through --cometchat-spacing-10
Shadows	--cometchat-shadow-1, --cometchat-shadow-2, --cometchat-shadow-3

2d. Sample app reference check (do this when 2a + 2b turned up nothing)

If 2b didn't find a CometChat<X> component for the user's request, don't immediately conclude they need custom code. The kit ships a reference sample app at:

https://github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app/src/components

with implementations for common chat UX patterns that combine multiple kit components but aren't shipped as single named exports. Examples that look like "missing components" but are in the sample app:

User asks for	Sample app reference path
User / group details panel	sample-app/src/components/CometChatDetails/CometChatUserDetails.tsx (group details is inline in CometChatHome.tsx's SideComponentGroup)
Threaded messages panel layout	sample-app/src/components/CometChatDetails/CometChatThreadedMessages.tsx
Top-level chat layout (left pane + main + side rail)	sample-app/src/components/CometChatHome/CometChatHome.tsx
Multi-tab chat (Chats / Calls / Users / Groups)	sample-app/src/components/CometChatSelector/CometChatTabs.tsx
New conversation dialog with user/group picker	Inline in CometChatHome.tsx as CometChatNewChatView (CSS: sample-app/src/styles/CometChatNewChat/CometChatNewChatView.css)
Search view (conversations + messages)	sample-app/src/components/CometChatSearchView/
Call log details / history / recordings	sample-app/src/components/CometChatCallLog/ (5 sub-files: Details, History, Info, Participants, Recordings)
App state / active-chat React context	sample-app/src/context/AppContext.jsx + appReducer.ts
Group ownership transfer modal	sample-app/src/components/CometChatTransferOwnership/

These patterns include matching CSS at sample-app/src/styles/<ComponentName>/ using BEM-style class names that are already wired to the kit's CSS variable system.

Discovery commands:

# List the sample app's components directory via the GitHub API
curl -s "https://api.github.com/repos/cometchat/cometchat-uikit-react/contents/sample-app/src/components?ref=v6" \
  | grep -oE '"name":\s*"[^"]+"' | head -30

# Fetch a specific component file directly
curl -s "https://raw.githubusercontent.com/cometchat/cometchat-uikit-react/v6/sample-app/src/components/CometChatDetails/CometChatUserDetails.tsx"

# Fetch its matching stylesheet
curl -s "https://raw.githubusercontent.com/cometchat/cometchat-uikit-react/v6/sample-app/src/styles/CometChatDetails/CometChatUserDetails.css"

You can also use WebFetch on the URLs above. The docs MCP does NOT index the sample app — you must fetch it from GitHub directly.

If you find a matching reference implementation:

1. Read BOTH the .tsx file AND its matching .css file (at sample-app/src/styles/<ComponentName>/)
2. Mirror the sample app's file/folder structure in the user's project, e.g. src/cometchat/CometChatDetails/CometChatUserDetails.tsx plus src/cometchat/CometChatDetails/CometChatDetails.css
3. Match the exact BEM class names from the sample (.cometchat-user-details__header, .cometchat-user-details__content-avatar, etc.) — they're already integrated with the kit's CSS variable system
4. Strip the sample app's local dependencies that the user's project doesn't have:
   • useContext(AppContext) → inline the values
   • getLocalizedString(...) → inline the English strings
   • cometchat-resources/ SVG icons → use Unicode equivalents or strip them
5. Tell the user: "The kit doesn't export this as a single component, but the official sample app has the reference implementation at cometchat/cometchat-uikit-react/v6/sample-app/.../CometChat<X>. I'm adapting it to your project."

2e. After discovery — decide what to do

In strict order, take the FIRST option that applies:

1. An existing component prop matches (2a): add the prop. Done. No new files. Most chat features land here.
2. A new component matches (2b) AND has its own styling: use the component as-is. Zero custom CSS.
3. A new component matches (2b) but you need layout glue: use the component; write minimal layout-only CSS that consumes --cometchat-* variables (per 2c).
4. Sample app has a reference implementation (2d): adapt the sample app pattern, mirroring its file structure and BEM class names.
5. None of the above: then (and only then) proceed to Step 3 to classify the request as a true customization.

Step 3 — Classify the customization

Read the user's request and place it into one of these buckets. The right approach is different per bucket: