Skip to main content
  • Goal: Override UI Kit color tokens to match your brand
  • Where: App.css (global) — import in app entry via import "./App.css";
  • Scope: Override variables on .cometchat (global) or .cometchat-<component> (component-specific)
  • Key tokens: --cometchat-primary-color (brand/accent), --cometchat-neutral-color-300 (incoming bubbles), --cometchat-background-color-01 (main background)
  • Dark mode: Override in .cometchat[data-theme="dark"] selector
  • Source file: css-variables.css on GitHub
  • Constraints: Global CSS only (no CSS Modules), no !important, component-level overrides take precedence over global

​
Introduction

The Chat UI Kit features a carefully crafted color palette designed for a consistent and visually appealing user experience. It follows the Block, Element, Modifier (BEM) methodology, ensuring scalable styling and easy customization by overriding the Kit’s CSS variables.
Agent Guardrails (Use These Rules)
  • Use the snippets exactly as shown; only change token values.
  • Keep .cometchat and .cometchat-conversations intact — these are the tested selectors.
  • Keep overrides in global CSS (App.css), not CSS Modules.
  • Dark mode examples assume data-theme is set on .cometchat. If you set data-theme elsewhere, update the selector to match.
Prerequisites before overriding any color tokens:
  1. Import the base stylesheet: @import url("@cometchat/chat-uikit-react/css-variables.css"); in your App.css
  2. Import your CSS file at the app entry: import "./App.css"; in App.tsx
  3. All overrides must target .cometchat or a .cometchat-<component> class
  4. Use global CSS (not CSS Modules with hashed class names) — hashed selectors won’t match

​
Selector Contract

Use these patterns when overriding colors. This is the canonical selector contract for this page. Global override 
.cometchat { --token: value; }
Component override 
.cometchat-conversations { --token: value; }
Dark mode override (default) 
.cometchat[data-theme="dark"] { --token: value; }
If you apply data-theme to a wrapper instead of .cometchat, scope the selector to match your DOM structure.

​
CSS Variable Reference

This table maps every commonly used token to what it visually controls. Use this to avoid hallucinating what a token does.
VariableWhat It ControlsDefault (Light)Used By
--cometchat-primary-colorBrand accent, outgoing bubble bg, active states, links, buttons#6852d6Outgoing bubbles, send button, active tabs, links
--cometchat-neutral-color-300Incoming bubble background#fffIncoming message bubbles
--cometchat-neutral-color-400Secondary backgrounds, dividersvariesBorders, secondary panels
--cometchat-neutral-color-500Muted text, placeholdersvariesPlaceholder text, disabled states
--cometchat-neutral-color-600Secondary textvariesTimestamps, subtitles
--cometchat-neutral-color-700Primary textvariesMain body text
--cometchat-neutral-color-800Headings, strong textvariesComponent titles, names
--cometchat-background-color-01Main app background#fffRoot container background
--cometchat-background-color-02Secondary/panel backgroundvariesSidebars, panels
--cometchat-background-color-03Tertiary backgroundvariesNested panels, cards
--cometchat-extended-primary-color-50 through 900Primary color scale (lightest to darkest)See palette belowHover states, gradients, shades
--cometchat-font-familyAll text in UI Kitsystem defaultGlobal typography
--cometchat-text-color-highlightHighlighted/linked textmatches primaryLinks, mentions, highlights
--cometchat-icon-color-highlightHighlighted icon colormatches primaryActive icons, selected states
--cometchat-text-color-secondarySecondary/caption textvariesTimestamps, subtitles, captions
--cometchat-icon-color-secondarySecondary icon colorvariesInactive icons
--cometchat-primary-button-backgroundPrimary button fillmatches primarySend button, action buttons
--cometchat-border-color-defaultDefault border colorvariesDividers, input borders
--cometchat-error-colorError states#f44336Error messages, validation
--cometchat-success-colorSuccess states#4caf50Online indicators, success messages
--cometchat-warning-colorWarning states#ff9800Warning callouts
CSS Specificity & Precedence Rules:
  1. Component-level overrides (.cometchat-conversations { --var: val }) take precedence over global overrides (.cometchat { --var: val })
  2. Dark mode overrides (.cometchat[data-theme="dark"]) take precedence over light mode defaults
  3. CSS variable overrides only affect properties the UI Kit theme binds to that variable — they do NOT change layout or spacing
  4. Always keep the .cometchat prefix to avoid leaking styles into the host app
  5. !important should never be needed — if it is, your selector specificity is wrong

​
Color Palette

The primary color defines key actions, branding, and UI elements, while the extended primary palette provides variations for supporting components.

​
Primary Color

​
Light Mode

--cometchat-primary-color: #6852d6;
--cometchat-extended-primary-color-50: #f9f8fd;
--cometchat-extended-primary-color-100: #edeafa;
--cometchat-extended-primary-color-200: #dcd7f6;
--cometchat-extended-primary-color-300: #ccc4f1;
--cometchat-extended-primary-color-400: #bbb1ed;
--cometchat-extended-primary-color-500: #aa9ee8;
--cometchat-extended-primary-color-600: #9a8be4;
--cometchat-extended-primary-color-700: #8978df;
--cometchat-extended-primary-color-800: #7965db;
--cometchat-extended-primary-color-900: #5d49be;

​
Dark Mode

--cometchat-primary-color: #6852d6;
--cometchat-extended-primary-color-50: #15102b;
--cometchat-extended-primary-color-100: #1d173c;
--cometchat-extended-primary-color-200: #251e4d;
--cometchat-extended-primary-color-300: #2e245e;
--cometchat-extended-primary-color-400: #362b6f;
--cometchat-extended-primary-color-500: #3e3180;
--cometchat-extended-primary-color-600: #473892;
--cometchat-extended-primary-color-700: #4f3ea3;
--cometchat-extended-primary-color-800: #5745b4;
--cometchat-extended-primary-color-900: #7460d9;

​
Extended Primary Colors

​
Light Mode

​
Dark Mode

​
Complete End-to-End Example: Custom Brand Colors

Step 1: Add to App.css: 
@import url("@cometchat/chat-uikit-react/css-variables.css");

/* Light mode brand override */
.cometchat {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-500: #fbaa75;
  --cometchat-extended-primary-color-900: #c45206;
  --cometchat-text-color-highlight: #f76808;
  --cometchat-icon-color-highlight: #f76808;
}

/* Dark mode brand override */
.cometchat[data-theme="dark"] {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-500: #7a3404;
  --cometchat-extended-primary-color-900: #fbaa75;
}
Step 2: Ensure App.tsx imports the CSS: 
import "./App.css";
// ... render CometChat UI Kit components
Expected result: All primary-colored elements (outgoing bubbles, buttons, active states, links) change from purple (#6852d6) to orange (#f76808) in both light and dark modes.

​
Common Failure Modes

SymptomCauseFix
CSS has no effectCSS file not imported in app entryAdd import "./App.css"; in App.tsx
CSS has no effectBase stylesheet not importedAdd @import url("@cometchat/chat-uikit-react/css-variables.css"); at top of App.css
Selectors don’t matchUsing CSS Modules (hashed class names)Move rules to a global stylesheet, not *.module.css
Only some elements changed colorOnly overrode --cometchat-primary-color but not extended paletteOverride the extended-primary-color scale too for full consistency
Dark mode unchangedOnly overrode light mode tokensAdd overrides in .cometchat[data-theme="dark"] selector too
Component-level override not workingSelector specificity too lowUse .cometchat .cometchat-<component> for higher specificity
Styles leak into host appMissing .cometchat scope prefixAlways scope overrides under .cometchat
Token change has no visible effectToken doesn’t control the property you expectCheck the CSS Variable Reference table above

​
Next Steps

Theming Overview

Global theming with CSS variables, fonts, and component-specific overrides

Message Bubble Styling

Customize incoming and outgoing message bubble colors per message type

Components Overview

Browse all available UI Kit components and their customization options

CSS Variables Source

View the complete CSS variables file on GitHub