Theming

Customize colors, fonts, spacing, and component styles using CSS custom properties and the data-theme attribute.

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).

---

Next Steps

Color Resources

Full color token reference with swatches

Message Bubble Styling

Customize bubble appearance, alignment, and spacing