Cometchat React V7 Customization

Ground truth: @cometchat/chat-uikit-react@7. Theming mechanism below is from the live v7 theming docs (see core references/docs-map.md → /ui-kit/react/theming). Status: catalog-verified vs installed 7.1.0 (exports-only web-v7.json). Fetch the full --cometchat-* token list from the theming .md twin ({DOCS_BASE}/ui-kit/react/theming.md, via docs-map.md) — do NOT bake it.

Companion skills (read first)

• cometchat-react-v7-core — install, provider, init→login→render. This skill ASSUMES it.

Use this skill when

Branding/theming: colors, fonts, light/dark mode, or per-component style overrides.

Prerequisites & install

Covered by core. No new package.

Customization mechanism (BAKED — v7)

• Design tokens = CSS custom properties, all prefixed --cometchat-*, scoped to the .cometchat wrapper.
• Light/dark: built-in light (default) and dark, selected via the theme prop on CometChatProvider and the data-theme attribute on the wrapper. Runtime switching via the useTheme hook.
• Follow the OS theme: the theme prop is "light" | "dark" only and defaults to light — there is no theme="system" and the kit does NOT read prefers-color-scheme (AUDIT-004). To follow the system light/dark setting, sync the theme prop to window.matchMedia("(prefers-color-scheme: dark)") (with a change listener, SSR-guarded). Recommended as the default for a fresh integration. Full recipe: cometchat-react-v7-core/references/theming.md.
• Import order: import your overrides AFTER the UI Kit styles (import UI Kit CSS ONCE at root).

import { CometChatProvider, useTheme } from "@cometchat/chat-uikit-react";
import "./cometchat-overrides.css";   // AFTER the kit styles

<CometChatProvider theme="dark"><>{/* your chat UI */}</></CometChatProvider>

.cometchat { --cometchat-font-family: "Inter", sans-serif; }             /* theme-INDEPENDENT tokens only */
.cometchat[data-theme="light"] { --cometchat-primary-color: #e91e63; }   /* per-theme COLOURS → data-theme attr */
.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
.cometchat-message-list { /* BEM class to scope tokens per component */ }

Per-theme COLOURS go on the data-theme element — NOT the bare .cometchat class (AUDIT-033). CometChatProvider renders one wrapper <div data-theme="light|dark" class="cometchat"> (compiled bundle: jsx("div",{ "data-theme": internalTheme, className: "cometchat" })), and the kit defines its tokens on [data-theme=light] / [data-theme=dark]. But several components render their OWN nested <div class="cometchat …"> with NO data-theme — verified for CometChatSearch (also popovers / portaled surfaces). So a colour on the bare .cometchat class ALSO lands on that nested wrapper and re-pins the base (light) value there: in dark mode the search stays light while everything else goes dark. Scope per-theme colours to .cometchat[data-theme="light"] / .cometchat[data-theme="dark"] so the nested wrapper matches neither and inherits the provider's theme. Keep only theme-independent tokens (font-family, radii) on bare .cometchat. (Earlier docs claimed [data-theme="dark"] .cometchat matches nothing — that's wrong: it DOES match those nested wrappers. It's still not the right selector for brand tokens; use the .cometchat[data-theme] form above.) To retint a kit INTERNAL per theme, use the kit's own pattern — [data-theme="dark"] .cometchat-message-list { … }.

What's swappable

• Global tokens on .cometchat (primary color, fonts, radii, spacing — fetch the full token names from the theming .md twin).
• Per-theme overrides via [data-theme="..."].
• Per-component scoping via BEM classes (.cometchat-conversations, .cometchat-message-list, …).
• Exact token names/defaults: fetch the theming .md twin ({DOCS_BASE}/ui-kit/react/theming.md, via core references/docs-map.md) — do NOT bake the token table.

Differentiating a nested surface — an opaque sub-surface needs its OWN var override (BAKED — verified vs 7.1.0)

Rule (general). A kit sub-surface that paints an OPAQUE background does NOT inherit a wrapper's background — its own opaque paint covers whatever the wrapper set. To differentiate a nested surface you MUST override THAT surface's own background CSS variable (scoped on an ancestor — it cascades into the variable, no internal-class override needed), not just set a background on the wrapper.

The thread panel is the canonical case. Verified in the 7.1.0 CSS: .cometchat-message-list paints background: var(--cometchat-message-list-bg) (default var(--cometchat-background-color-03)); .cometchat-thread-header and .cometchat-message-composer paint their own opaque var(--cometchat-background-color-01). So the thread's message list renders -03 — the SAME shade as the main list, and different from its own header/composer — and a background on the thread wrapper alone can't fix it (the list covers it). Override the list's own token on the thread wrapper:

/* the div you wrap CometChatThreadHeader + thread CometChatMessageList + CometChatMessageComposer in */
.cc-thread-panel {
  --cometchat-message-list-bg: var(--cometchat-background-color-01); /* matches the thread header/composer; differs from the main list's -03 */
  border-left: 1px solid var(--cometchat-border-color-default, #e8e8e8); /* optional divider from the main pane (-default = neutral-300 = #e8e8e8 light / #383838 dark) */
}

--cometchat-background-color-01 is #ffffff (light) / #141414 (dark) and -03 is #f5f5f5 (light) / #272727 (dark) — so the override visibly separates the thread list from the main list in BOTH themes while matching the thread header/composer. Same trick for any per-surface background: scope the surface's OWN token on the wrapper, never override the kit's internal .cometchat-* element classes (core/references/anti-patterns.md #7/#12/#16).

Tinting the thread HEADER specifically — use its dedicated token. .cometchat-thread-header paints background: var(--cometchat-thread-header-background, var(--cometchat-background-color-01, #fff)) (verified vs 7.1.0 — dist/index.css:12727; the token is NOT defined in :root, only referenced with that fallback chain). So if you want to give the thread HEADER its own tint (a different shade from the list/composer, e.g. a subtly darker panel header), set --cometchat-thread-header-background directly on the thread wrapper — cleaner and more targeted than leaning on the -01 fallback:

.cc-thread-panel {
  --cometchat-message-list-bg: var(--cometchat-background-color-01);  /* REQUIRED — repaints the thread LIST (opaque, covers the wrapper) */
  --cometchat-thread-header-background: var(--cometchat-background-color-02);  /* OPTIONAL — tints ONLY the thread header, independent of the list */
}

The --cometchat-message-list-bg override above is still required — the header token only paints the header; it does not touch the opaque message list. Use --cometchat-thread-header-background only when you want the header a different shade from the list; if you want them to match, the header already inherits -01 and needs no override.