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 { … }.