---
name: cometchat-angular-v5-customization
description: "Brand and customize the CometChat Angular UI Kit — CSS variable tokens, light/dark via ThemeService, localization, date/time formats, global config, and swapping component regions with ng-template. Triggers: 'change the chat colours', 'match my brand angular', 'dark mode', 'translate the chat', 'change the date format', 'custom avatar in the list'."
license: "MIT"
compatibility: "@cometchat/chat-uikit-angular ^5 (5.1.0–5.2.2 verified); Angular 17-21"
metadata:
author: "CometChat"
version: "1.0.0"
tags: "cometchat angular customization theming v5 branding dark-mode localization tokens"
---
> **Ground truth:** `@cometchat/chat-uikit-angular@5` (5.1.0–5.2.2 verified). Theme tokens, `ThemeService` and the global config are FETCHED from `{DOCS_BASE}/ui-kit/angular/customization/theming.md`, `/customization/global-config.md`, `/customization/localization.md`, `/customization/date-time-formatting.md` and `/message-bubble-styling.md` — base + paths in `cometchat-angular-v5-core/references/docs-map.md`. CSS variable names are version-pinned; never invent a token.
## Companion skills (read first)
- `cometchat-angular-v5-core` — install and `references/theming.md` for the token basics. Assumed.
- `cometchat-angular-v5-components` — view slots, when the change is structural rather than visual.
## Use this skill when
Changing how the kit **looks or reads**: colours, fonts, dark mode, language, date formats, or replacing a region's markup.
**Cloning a named app, or mixing kit components with your own UI?** Measure the target's colors, type, spacing and radii into ONE token source, theme the kit from it, and style every custom component from the same tokens so kit and custom parts look like one design; host a kit component in your own dialog/panel when only its placement differs. Flow: `cometchat-onboarding` → `references/clone-mode.md` (Design sync, build levels L0–L6).
## Pick the smallest lever
| Want | Use | Cost |
| --- | --- | --- |
| Different colours / spacing | CSS variables | one stylesheet |
| Light ↔ dark | `ThemeService` | one line |
| Different language | `CometChatLocalize` | config |
| Different date format | per-component `*DateTimeFormat` inputs | one input |
| Different markup in a region | `*View` slot + `ng-template` | a template |
| Different behaviour | not customization — see `features` or `components` | — |
Reach for the first that works. Replacing a whole region to change a colour throws away selection, presence and receipts.
## CSS variables
Every visual is a `--cometchat-*` custom property. Override wherever it cascades — usually `styles.css`.
```css
:root {
--cometchat-primary-color: #6851D6;
--cometchat-border-color-default: #DCDCDC;
--cometchat-text-color-primary: #141414;
}
```
Scope to part of the app by setting them on a wrapper instead of `:root`. Full token list: `{DOCS_BASE}/ui-kit/angular/customization/theming.md`.
Never target generated class names with descendant selectors — they change between releases. Never use `!important`; if a token is not applying, the kit stylesheet is not registered (`angular.json` → `styles`) or your rule is not in the cascade path.
## Light / dark — ThemeService does it all
```ts
import { Component, inject } from '@angular/core';
import { ThemeService } from '@cometchat/chat-uikit-angular';
@Component({ selector: 'app-root', standalone: true, template: '' })
export class AppComponent {
constructor() { inject(ThemeService).initFromPreference(); }
}
```
That single call respects the OS `prefers-color-scheme`, applies `data-theme` to `` via the `DOCUMENT` token (SSR-safe), and keeps its own `matchMedia` listener so the UI follows the OS live.
> ⚠️ **It does NOT persist, despite its docstrings.** Verified against shipped 5.1.0: `initFromPreference()` claims to read `localStorage` first and `setTheme()`/`toggleTheme()` claim to persist, but the class never touches `localStorage` — a manual toggle is lost on reload. If the user needs a toggle that survives reload, add persistence **around** the service (`cometchat-angular-v5-core/references/theming.md`) rather than replacing it; a second `matchMedia` listener will drift from `currentTheme()`.
Toggle: `themeService.toggleTheme()` — do not compute the next value yourself. Set a specific mode: `themeService.setTheme('dark')`. Read: `themeService.currentTheme()` — a signal, so it works directly in templates.
> **Divergence from the docs.** `{DOCS_BASE}/ui-kit/angular/customization/theming.md` documents `setTheme()`, `toggleTheme()` and setting `data-theme` by hand, but does **not** mention `initFromPreference()` or following the OS `prefers-color-scheme`. `initFromPreference()` is real and verified against the installed 5.1.0 kit — prefer it over a hand-written `matchMedia` listener. Do not "correct" it away because the guide omits it; the omission is a docs gap, not evidence the method is wrong.
> Do **not** hand-roll a `matchMedia('(prefers-color-scheme: dark)')` listener. That is the React recipe; React's kit cannot read the OS. Angular's can, and duplicating it creates state that drifts from `currentTheme()`.
## Localization
`CometChatLocalize` ships 19 languages. Set the language once at startup; the `TranslatePipe` and `getLocalizedString()` read from it. To override individual strings or add a language, fetch `{DOCS_BASE}/ui-kit/angular/customization/localization.md` — the override shape is version-specific and worth reading rather than guessing.
## Date & time formats
Per-component inputs, not global CSS: `lastMessageDateTimeFormat` (conversations), `messageSentAtDateTimeFormat` (search), `callInitiatedDateTimeFormat` (call logs), `lastActiveAtDateTimeFormat` (message header). Pipes `CalendarDatePipe`, `MessageDatePipe` and `ConversationDatePipe` are exported if you need the same formatting in your own markup.
## Global config
`COMETCHAT_GLOBAL_CONFIG` is an injection token for app-wide kit defaults. Prefer it over repeating the same input on every component instance. Details: `{DOCS_BASE}/ui-kit/angular/customization/global-config.md`.
## Structural changes
Replacing markup rather than styling it is a **view slot** — `itemView`, `titleView`, `subtitleView`, `leadingView`, `trailingView`, `headerView`, `emptyView`, `errorView`, `loadingView`. See `cometchat-angular-v5-components`. Override the smallest slot that does the job.
### Avatar and sender name on every message (BAKED — verified vs 5.2.2, same code in 5.1.0 and 5.2.0)
What to check and why: `cometchat-onboarding/references/clone-mode.md` → *Message chrome*. This is the Angular how-to.
**Kit default:** avatar and sender name on every LEFT-aligned (incoming) message, in 1:1 chats AND groups; your own messages sit on the right with neither. The bubble's rule is `alignment === left` with no group check (`shouldShowLeadingView` / `shouldShowHeaderView` in `CometChatMessageBubbleComponent`); call and action rows are centered and never get them.
When the target shows avatars and names (Slack, Discord, Teams), do BOTH steps yourself, without asking. Together they put your avatar and name on every message, own and others', in 1:1 chats and groups:
1. **Alignment:** `[messageAlignment]="align"` with `align = MessageListAlignment.left` on ``. Everything moves left, so your own messages get the avatar and name too. The enum is numeric (`left = 0`, `standard = 1`); the docs' `[messageAlignment]="'left'"` is a strict-template error (TS2322) and would not match at runtime anyway.
2. **Per-message slots:** register a `leadingView` (avatar) and `headerView` (name) through `MessageBubbleConfigService` (root singleton; `setGlobalViews` covers every message type). A registered slot renders even on right-aligned bubbles, so this also works if the target keeps your own messages on the right, and it is where the target's own avatar size and name style go:
```ts
import { Component, Input, OnDestroy, OnInit, TemplateRef, ViewChild, inject } from '@angular/core';
import type { BaseMessage, Group, User } from '@cometchat/chat-sdk-javascript';
import { CometChatAvatarComponent, CometChatMessageListComponent, MessageBubbleConfigService, MessageListAlignment } from '@cometchat/chat-uikit-angular';
@Component({
selector: 'app-channel-messages',
standalone: true,
imports: [CometChatMessageListComponent, CometChatAvatarComponent],
template: `
{{ m.getSender()?.getName() }}
`,
})
export class ChannelMessagesComponent implements OnInit, OnDestroy {
@Input() user?: User;
@Input() group?: Group;
readonly align = MessageListAlignment.left;
@ViewChild('senderAvatar', { static: true }) senderAvatar!: TemplateRef<{ $implicit: BaseMessage }>;
@ViewChild('senderName', { static: true }) senderName!: TemplateRef<{ $implicit: BaseMessage }>;
private readonly bubbles = inject(MessageBubbleConfigService);
// static: true -> the templates exist in ngOnInit, before the list renders its first bubble.
ngOnInit(): void { this.bubbles.setGlobalViews({ leadingView: this.senderAvatar, headerView: this.senderName }); }
// Root singleton: clear on destroy, or every other message list keeps a dead template.
ngOnDestroy(): void { this.bubbles.setGlobalViews({ leadingView: null, headerView: null }); }
}
```
The slot context is `{ $implicit: message }`. Style `.cc-sender-name` from your token source (e.g. `font: 600 15px var(--cometchat-font-family)`). Multi-attachment batches show the avatar and name once by themselves (the list passes `hideAvatar` / `hideSenderName` to the follow-on bubbles, which also hides your slot). `hideAvatar` on the list, or `hideAvatar` in `COMETCHAT_GLOBAL_CONFIG`, still wins over the slot; check both are unset. Service API: `{DOCS_BASE}/ui-kit/angular/components/cometchat-message-list.md` (MessageBubbleConfigService section).
- **Once per run** isn't reachable: the slot only receives its own message, not the previous one (L4).
- **Verified:** names and logic read from the shipped 5.2.2 fesm2022 + `.d.ts` (5.1.0 and 5.2.0 identical); snippet compiles with `ng build` `strictTemplates` + strict TS. Not yet run in a browser: open a 1:1 chat and a group and check your own and others' messages.
## Common pitfalls
1. **Hand-rolling OS theme detection** — `ThemeService.initFromPreference()` already does it.
2. **Replacing `itemView` for a colour change** — loses selection, presence and receipts.
3. **Styling generated class names** — breaks on the next kit release.
4. **`!important` wars** — the stylesheet is not registered, or the rule is out of cascade.
5. **Two theme sources** — `ThemeService` plus your own `data-theme` writer; they drift.
## Verify it works
Brand colours apply in both themes · dark mode survives a reload ONLY if you persisted the choice yourself (the kit does not — see the warning above); without that, a reload falls back to the OS setting · the OS theme is respected on first load · localized strings render · overridden regions keep click, presence and receipts working.
## Explain what you built (REQUIRED close)
Tell the developer what changed, naming the files: what you themed — which tokens changed and whether light/dark follows the OS. Flag anything dev-only as dev-only, and say what you did **not** touch — this is additive.
**Then offer these THREE options as a SELECTABLE choice and WAIT for the pick — never auto-continue (`RULES.md` §19):**
1. **Add another feature** → a feature from `features.angular-v5.json`, or deeper structural customization via view slots. **Never offer an `auto` entry** (reactions, mentions, receipts, typing, media) — those are core in v5 and already on.
2. **Add a feature** (search, calls, polls, AI) → `cometchat-angular-v5-features`.
3. **Test it manually** → do nothing further; hand back so the user runs it.