Theming

AI Integration Quick Reference

Field	Value
Theme prop	`theme="light"` or `theme="dark"` on `CometChatProvider`
Root selector	`.cometchat` (wrapper div with `data-theme` attribute)
Token prefix	`--cometchat-*`
Built-in themes	`light` (default), `dark`
Custom theme	Override CSS variables on `.cometchat` or `[data-theme="custom"]`

Overview

The v7 UI Kit uses CSS custom properties (design tokens) for all visual styling. Every color, font, spacing value, and border radius is defined as a --cometchat-* variable. Components reference these tokens — never hardcoded values. Theming works through the data-theme attribute on the .cometchat wrapper div. The built-in light.css and dark.css files define token values for each theme. You can override any token to create custom themes.

Setting the Theme

Pass the theme prop to CometChatProvider:

<CometChatProvider theme="dark">
  <MyChatApp />
</CometChatProvider>

This sets data-theme="dark" on the wrapper, which activates the dark theme CSS variables.

Switching Themes at Runtime

Use the useTheme hook inside any component within the provider:

import { useTheme } from "@cometchat/chat-uikit-react";

function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Current: {theme}
    </button>
  );
}

Customizing Tokens

Override CSS variables to change the look of all components at once:

src/cometchat-overrides.css

.cometchat {
  --cometchat-primary-color: #e91e63;
  --cometchat-font-family: "Inter", sans-serif;
  --cometchat-radius-3: 16px;
}

Import this file after the UI Kit styles:

import "./cometchat-overrides.css";

Per-Theme Overrides

Target a specific theme with the data-theme selector:

[data-theme="dark"] .cometchat {
  --cometchat-primary-color: #bb86fc;
  --cometchat-background-color-01: #121212;
}

Per-Component Overrides

Target a specific component by its BEM class name:

.cometchat-conversations {
  --cometchat-background-color-01: #f5f5f5;
}

.cometchat-message-list {
  --cometchat-background-color-01: #fafafa;
}

Or wrap the component in your own class:

.my-sidebar {
  --cometchat-background-color-01: #f5f5f5;
}

Design Token Categories

Colors

Token	Purpose
`--cometchat-primary-color`	Brand color (buttons, links, highlights)
`--cometchat-extended-primary-color-50` to `900`	Primary color scale (50 = lightest)
`--cometchat-neutral-color-50` to `900`	Gray scale for backgrounds, borders, text
`--cometchat-info-color`	Informational (blue)
`--cometchat-warning-color`	Warning (amber)
`--cometchat-success-color`	Success (green)
`--cometchat-error-color`	Error (red)
`--cometchat-static-black`	Always black regardless of theme
`--cometchat-static-white`	Always white regardless of theme

Semantic Colors

Token	Purpose
`--cometchat-background-color-01` to `04`	Background layers (01 = base, 04 = elevated)
`--cometchat-border-color-light` / `default` / `dark` / `highlight`	Border variants
`--cometchat-text-color-primary` / `secondary` / `tertiary` / `disabled` / `highlight`	Text colors
`--cometchat-icon-color-primary` / `secondary` / `tertiary` / `highlight`	Icon colors

Typography

Token	Value format
`--cometchat-font-family`	Font stack (default: `'Roboto', 'Inter', sans-serif`)
`--cometchat-font-title-bold`	`700 32px/38.4px var(--cometchat-font-family)`
`--cometchat-font-heading1-bold` through `heading4-regular`	Heading scales
`--cometchat-font-body-bold` / `medium` / `regular`	Body text (14px)
`--cometchat-font-caption1-bold` / `medium` / `regular`	Small text (12px)
`--cometchat-font-caption2-bold` / `medium` / `regular`	Smallest text (10px)

Spacing & Layout

Token	Purpose
`--cometchat-spacing` to `--cometchat-spacing-20`	Spacing scale (2px increments: 2, 4, 8, 12, 16, …, 80)
`--cometchat-padding` to `--cometchat-padding-10`	Padding (maps to spacing)
`--cometchat-margin` to `--cometchat-margin-20`	Margin (maps to spacing)
`--cometchat-radius` to `--cometchat-radius-6`	Border radius scale
`--cometchat-radius-max`	Fully rounded (1000px)

Buttons

Token	Purpose
`--cometchat-primary-button-background`	Primary button background
`--cometchat-primary-button-text`	Primary button text color
`--cometchat-primary-button-icon`	Primary button icon color
`--cometchat-secondary-button-background`	Secondary button background
`--cometchat-secondary-button-text`	Secondary button text color
`--cometchat-fab-button-background`	Floating action button background

Component CSS Classes

The UI Kit uses plain, unhashed BEM class names in the DOM. All component class names follow the pattern cometchat-{component} with BEM modifiers (e.g., cometchat-message-bubble__content--outgoing). You can target them directly with standard class selectors.

What Works

1. The .cometchat wrapper class — the root div. Override tokens here to affect all components:

.cometchat {
  --cometchat-primary-color: #e91e63;
  --cometchat-font-family: "Inter", sans-serif;
}

2. Plain class selectors — target any component by its BEM class name:

.cometchat-conversations {
  --cometchat-background-color-01: #f5f5f5;
}

.cometchat-message-list {
  --cometchat-background-color-01: #fafafa;
}

3. Wrap in your own class — add a wrapper div with your own class and set tokens there:

<div className="my-chat-sidebar">
  <CometChatConversations />
</div>

.my-chat-sidebar {
  --cometchat-background-color-01: #f5f5f5;
  --cometchat-primary-color: #1976d2;
}

CSS variable overrides work at any level of the tree. Set them on .cometchat (the root wrapper) to affect all components, or use class selectors / wrapper classes to scope the change. Variables cascade down — a value set on a parent will be inherited by all CometChat components within it.

Creating a Custom Theme

Define a complete set of tokens under a custom data-theme value:

src/themes/brand.css

[data-theme="brand"] {
  --cometchat-primary-color: #e91e63;
  --cometchat-extended-primary-color-500: #e91e63;
  --cometchat-background-color-01: #fce4ec;
  --cometchat-background-color-02: #f8bbd0;
  --cometchat-font-family: "Poppins", sans-serif;
  /* ... override all tokens as needed */
}

Then pass your theme name:

<CometChatProvider theme="brand">

When creating a custom theme, start from the light or dark theme file and override only what you need. Unset tokens will fall back to the :root defaults (light theme).

Overview

Setting the Theme

Switching Themes at Runtime

Customizing Tokens

Per-Theme Overrides

Per-Component Overrides

Design Token Categories

Colors

Semantic Colors

Typography

Spacing & Layout

Buttons

Component CSS Classes

What Works

Creating a Custom Theme

Next Steps

Color Resources

Message Bubble Styling

​Overview

​Setting the Theme

​Switching Themes at Runtime

​Customizing Tokens

​Per-Theme Overrides

​Per-Component Overrides

​Design Token Categories

​Colors

​Semantic Colors

​Typography

​Spacing & Layout

​Buttons

​Component CSS Classes

​What Works

​Creating a Custom Theme

​Next Steps

Color Resources

Message Bubble Styling

Overview

Setting the Theme

Switching Themes at Runtime

Customizing Tokens

Per-Theme Overrides

Per-Component Overrides

Design Token Categories

Colors

Semantic Colors

Typography

Spacing & Layout

Buttons

Component CSS Classes

What Works

Creating a Custom Theme

Next Steps