> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Customizing UI With Theming

> Customize the CometChat React UI Kit appearance using CSS variables for colors, fonts, dark mode, and component-specific styling.

<Accordion title="AI Integration Quick Reference">
  | Field              | Value                                                                                                                                                              |
  | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
  | Goal               | Customize UI Kit appearance (colors, fonts, dark mode) via CSS variables                                                                                           |
  | Where              | `App.css` (global) — imported in app entry via `import "./App.css";`                                                                                               |
  | Step 1             | Import base stylesheet: `@import url("@cometchat/chat-uikit-react/css-variables.css");`                                                                            |
  | Step 2             | Override variables on `.cometchat` (global) or `.cometchat-<component>` (component-specific)                                                                       |
  | Step 3 (dark mode) | Override on `.cometchat-root[data-theme="dark"] .cometchat` or use `@media (prefers-color-scheme: dark)`                                                           |
  | Key tokens         | `--cometchat-primary-color`, `--cometchat-neutral-color-300`, `--cometchat-font-family`, `--cometchat-background-color-03`                                         |
  | Constraints        | Global CSS only (no CSS Modules), no `!important`, component-level overrides beat global                                                                           |
  | Full token list    | [Color Resources](/ui-kit/react/theme/color-resources) \| [GitHub source](https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/styles/css-variables.css) |
</Accordion>

Theming controls the look and feel of the chat UI — colors, fonts, and other styles — through CSS variables.

<Warning>
  Prerequisites:

  1. Import the base stylesheet: `@import url("@cometchat/chat-uikit-react/css-variables.css");` in `App.css`
  2. Import the CSS file at the app entry: `import "./App.css";` in `App.tsx`
  3. All selectors assume the UI Kit renders under a `.cometchat` root wrapper
  4. Use global CSS (not CSS Modules with hashed class names) — hashed selectors won't match
</Warning>

***

## Root Wrapper (`.cometchat`)

All selectors in this doc are scoped under `.cometchat`, the class the UI Kit renders on its root element.

```tsx lines theme={null}
export default function App() {
  return (
    <div className="cometchat-root">
      {/* UI Kit components */}
    </div>
  );
}
```

For `data-theme`, place it on the wrapper and scope dark theme overrides to `.cometchat` inside.

***

## Theming Contract

**Inputs**

* Base stylesheet import: `@import url("@cometchat/chat-uikit-react/css-variables.css");`
* Global CSS variables on `.cometchat`
* Component-scoped variables on `.cometchat .cometchat-<component>`
* Optional element-level CSS overrides for specific selectors
* Optional theme mode selector: `.cometchat-root[data-theme="dark"] .cometchat` or `@media (prefers-color-scheme: dark)`

**Precedence**

1. Element-level CSS overrides (most specific)
2. Component-scoped variables (`.cometchat .cometchat-conversations { --var }`)
3. Global variables (`.cometchat { --var }`)
4. Defaults from `css-variables.css` (least specific)

**Outputs**

* Primary tokens change outgoing bubbles, buttons, and active states
* Background tokens change panels and surfaces
* Text/icon tokens change highlight accents
* Font tokens change typography across the UI

***

## Importing the Stylesheet

```css title="App.css" lines theme={null}
@import url("@cometchat/chat-uikit-react/css-variables.css");
```

***

## Global Theming with CSS Variables

Override CSS variables in the global stylesheet to customize the entire chat UI.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/veBAxaR1km9EBnSg/images/37d11669-theming_global_css_custom-2574c11cb6d3d362fcb498d8fa613afd.png?fit=max&auto=format&n=veBAxaR1km9EBnSg&q=85&s=e0a2231c724033166296c11154c51c7f" width="1282" height="802" data-path="images/37d11669-theming_global_css_custom-2574c11cb6d3d362fcb498d8fa613afd.png" />
</Frame>

<Tip>
  Use `App.css` for global overrides scoped under `.cometchat`. Use the runtime `setProperty` approach only for live theme changes without a reload.
</Tip>

<Tabs>
  <Tab title="App.css (Recommended)">
    ```css lines theme={null}
    .cometchat {
      --cometchat-primary-color: #f76808;
      --cometchat-neutral-color-300: #E8E8E8;
      --cometchat-background-color-03: #feede1;
      --cometchat-extended-primary-color-500: #fbaa75;
      --cometchat-icon-color-highlight: #f76808;
      --cometchat-text-color-highlight: #f76808;
    }
    ```
  </Tab>

  <Tab title="App.tsx (Runtime Only)">
    ```tsx lines theme={null}
    import { useEffect } from "react";

    const App = () => {
      useEffect(() => {
        document.documentElement.style.setProperty(
          "--cometchat-font-family",
          "'Times New Roman'"
        );
      }, []);

      return <div className="cometchat-root">{/* Chat UI here */}</div>;
    };

    export default App;
    ```
  </Tab>
</Tabs>

All primary-colored elements (outgoing bubbles, buttons, active states, links) change to orange (#f76808). Background panels change to light peach (#feede1). Font changes to Times New Roman.

***

## Top Tokens (Quick Mapping)

For the complete list, see [Color Resources](/ui-kit/react/theme/color-resources).

| Token                                    | Common usage                                                    |
| ---------------------------------------- | --------------------------------------------------------------- |
| `--cometchat-primary-color`              | Primary accent color (buttons, outgoing bubbles, active states) |
| `--cometchat-extended-primary-color-900` | Darker primary shade (outgoing bubble shade)                    |
| `--cometchat-extended-primary-color-500` | Mid primary shade (secondary accents/hover)                     |
| `--cometchat-neutral-color-300`          | Neutral surface (incoming bubbles/panels)                       |
| `--cometchat-background-color-03`        | Panel background surface                                        |
| `--cometchat-text-color-highlight`       | Highlight text color                                            |
| `--cometchat-icon-color-highlight`       | Highlight icon color                                            |
| `--cometchat-message-seen-color`         | Seen/read indicator color                                       |
| `--cometchat-font-family`                | Global font family (`'Roboto', 'Inter'` default)                |
| `--cometchat-radius-max`                 | Maximum corner radius used across UI elements                   |

***

## Component-Specific Theming

Override CSS variables within a component's class to apply different styles to specific components.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/-YC7tOebleeoFejE/images/e70eabdc-theming_component_wise_css_custom-cdacb569db3c0daa22cfe51c6f2ae93f.png?fit=max&auto=format&n=-YC7tOebleeoFejE&q=85&s=d93d771f16d49409b65f7d411ad69afa" width="1282" height="802" data-path="images/e70eabdc-theming_component_wise_css_custom-cdacb569db3c0daa22cfe51c6f2ae93f.png" />
</Frame>

```css title="App.css" lines theme={null}
.cometchat .cometchat-conversations {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-500: #fbaa75;
  --cometchat-text-color-highlight: #ffab00;
  --cometchat-message-seen-color: #f76808;
  --cometchat-radius-max: 12px;
}
```

Only the Conversations component changes — primary color becomes orange, highlight text becomes amber, avatars get 12px border radius. Other components remain unchanged.

***

## Advanced Customization with CSS Overrides

Target specific elements directly for full control over component styling.

```css title="App.css" lines theme={null}
.cometchat-conversations .cometchat-avatar,
.cometchat-conversations .cometchat-avatar__image {
  border-radius: 12px;
}
```

Avatar images in the Conversations list change from circular to rounded-square (12px radius).

***

## Dark and Light Theme Support

<Tip>
  Choose ONE dark mode strategy:

  1. App-controlled: set `data-theme` on the wrapper (e.g., `.cometchat-root`) and scope overrides like `.cometchat-root[data-theme="dark"] .cometchat { ... }`
  2. OS-controlled: use `@media (prefers-color-scheme: dark)` scoped to `.cometchat`
</Tip>

### Enabling Dark Mode

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/veBAxaR1km9EBnSg/images/3a7b0c73-theming_dark_mode_default-fff438886065da229f12cfb3b8904f27.png?fit=max&auto=format&n=veBAxaR1km9EBnSg&q=85&s=949bc2ddd06be2092d3e8bab2546fb70" width="1282" height="802" data-path="images/3a7b0c73-theming_dark_mode_default-fff438886065da229f12cfb3b8904f27.png" />
</Frame>

```tsx title="App.tsx" lines theme={null}
import { useEffect, useState } from "react";

const App = () => {
  const [theme, setTheme] = useState("light");

  useEffect(() => {
    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
    setTheme(mediaQuery.matches ? "dark" : "light");

    const handleThemeChange = (e: MediaQueryListEvent) => {
      setTheme(e.matches ? "dark" : "light");
    };

    mediaQuery.addEventListener("change", handleThemeChange);
    return () => mediaQuery.removeEventListener("change", handleThemeChange);
  }, []);

  return <div className="cometchat-root" data-theme={theme}>{/* Chat UI here */}</div>;
};

export default App;
```

The wrapper tracks the user's OS preference and sets `data-theme`, which switches palettes in CSS.

### Customizing Light and Dark Theme

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/bKHmaxDqzaJZWwLS/images/48cb156f-theming_dark_mode_custom-67a196da9f0a1f88f5c1e81fed12f7f4.png?fit=max&auto=format&n=bKHmaxDqzaJZWwLS&q=85&s=052ee937f472e1da0e883c7ea5b56ded" width="1282" height="802" data-path="images/48cb156f-theming_dark_mode_custom-67a196da9f0a1f88f5c1e81fed12f7f4.png" />
</Frame>

```css title="App.css" lines theme={null}
/* Default (Light) Theme */
.cometchat {
  --cometchat-primary-color: #f76808;
  --cometchat-neutral-color-300: #E8E8E8;
  --cometchat-background-color-03: #feede1;
  --cometchat-extended-primary-color-500: #fbaa75;
  --cometchat-icon-color-highlight: #f76808;
  --cometchat-text-color-highlight: #f76808;
}

/* Dark Theme */
.cometchat-root[data-theme="dark"] .cometchat {
  --cometchat-primary-color: #f76808;
  --cometchat-neutral-color-300: #311502;
  --cometchat-background-color-03: #451d02;
  --cometchat-extended-primary-color-500: #943e05;
  --cometchat-icon-color-highlight: #f76808;
  --cometchat-text-color-highlight: #f76808;
  --cometchat-message-seen-color: #f76808;
  --cometchat-neutral-color-50: #1a1a1a;
}
```

For OS-controlled dark mode, wrap the dark overrides in `@media (prefers-color-scheme: dark)` and keep the `.cometchat` scope.

Light mode uses orange (#f76808) with peach backgrounds; dark mode uses the same orange accent but with dark brown backgrounds (#311502, #451d02) for proper contrast.

***

## Examples

### Brand color swap (global)

```css title="App.css" lines theme={null}
.cometchat {
  --cometchat-primary-color: #0f766e;
  --cometchat-extended-primary-color-500: #14b8a6;
  --cometchat-text-color-highlight: #0f766e;
  --cometchat-icon-color-highlight: #0f766e;
}
```

Primary accents, buttons, and active states switch to teal.

### Dark mode (app-controlled)

```css title="App.css" lines theme={null}
.cometchat-root[data-theme="dark"] .cometchat {
  --cometchat-background-color-03: #121212;
  --cometchat-neutral-color-300: #1e1e1e;
  --cometchat-text-color-highlight: #f76808;
}
```

Panels and surfaces darken while accents remain visible.

### Conversations-only override

```css title="App.css" lines theme={null}
.cometchat .cometchat-conversations {
  --cometchat-primary-color: #f76808;
  --cometchat-message-seen-color: #f76808;
  --cometchat-radius-max: 12px;
}
```

Only the Conversations component changes; other components stay default.

### Bubble styling (incoming/outgoing)

```css title="App.css" lines theme={null}
.cometchat .cometchat-message-bubble-outgoing .cometchat-message-bubble__body {
  --cometchat-primary-color: #f76808;
  --cometchat-extended-primary-color-900: #fbaa75;
}

.cometchat .cometchat-message-bubble-incoming .cometchat-message-bubble__body {
  --cometchat-neutral-color-300: #f1f5f9;
}
```

Outgoing bubbles use orange; incoming bubbles use a light slate. For more variants, see [Message Bubble Styling](/ui-kit/react/theme/message-bubble-styling).

## Resources

<CardGroup>
  <Card title="UI Kit Source Code">
    Complete list of color variables and hex values on GitHub.

    [View on GitHub](https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/styles/css-variables.css#L198-L419)
  </Card>

  <Card title="Figma UI Kit">
    Figma UI Kit with fully integrated color palette.

    [View on Figma](https://www.figma.com/community/file/1442863561340379957/cometchat-ui-kit-for-web)
  </Card>
</CardGroup>