--- name: cometchat-angular-customization description: "Customize the CometChat Angular UI Kit v5 (@cometchat/chat-uikit-angular@5) without forking — four-tier model: Angular @Input slot views → request builders → text formatters + message-action options + per-type bubble views → event bus. Standalone components, ng-template slots, no NgModule, no DataSource." license: "MIT" compatibility: "Angular >=17 <22; @cometchat/chat-uikit-angular ^5.0" metadata: author: "CometChat" version: "4.0.0" tags: "cometchat angular customization v5 formatters events templates ng-template slot-views options standalone" --- ## Purpose Teaches Claude how to change the behaviour or appearance of the CometChat **Angular UI Kit v5** (`@cometchat/chat-uikit-angular@5`) **without modifying the kit itself**. Four tiers, from cheapest to deepest: ``` Tier 1 — Slot views (@Input ng-template) (95% of asks solved here) Tier 2 — RequestBuilder (filter what data loads) Tier 3 — Formatters + message-action options + per-type bubble views Tier 4 — Event bus (react to kit activity) ``` **Always try Tier 1 first.** Escalate only when the tier can't do what the user wants. **Read `cometchat-angular-core` first, then `cometchat-angular-components`.** The component catalog is the source of truth for the exact `@Input` slot-view names, `@Output` events, and request-builder inputs that this skill builds on. Never invent a binding — if it isn't in the catalog or the bundled `.d.ts`, it doesn't exist. Ground truth: `@cometchat/chat-uikit-angular@5.0.2` bundled types (`node_modules/@cometchat/chat-uikit-angular/types/cometchat-chat-uikit-angular.d.ts`) + `docs/ui-kit/angular`. Verify any non-obvious symbol against the installed `.d.ts` before relying on it. **Official docs:** https://www.cometchat.com/docs/ui-kit/angular/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). --- ## v5 reset — what is NOT here (if you've seen the v4 Angular kit) v5 is a clean break from the v4 (NgModule, Angular 12–15) customization model. These v4 symbols are **gone** — do not import or reference them: | v4 symbol (phantom in v5) | v5 replacement | |---|---| | `CometChatMessageTemplate` | per-type bubble views via `MessageBubbleConfigService.setBubbleView(type, partMap)`, **or** the `bubbleFooterView` / `appendView` slot inputs (Tier 3c) | | `DataSource` / `DataSourceDecorator` / `ChatConfigurator` | request builders (Tier 2) + the `MessageBubbleConfigService` / `CometChatTemplatesService` injected services | | `templates` @Input on `` | **does not exist** — use `optionsOverride` / `additionalOptions` for actions and `MessageBubbleConfigService` for bubbles | | `CometChatTextFormatter` v4 API (`setRegexPatterns`, `getFormattedText(input)`, `getOriginalText(input)`) | v5 API: abstract `id`, `getRegex()`, `format(text)`, optional `shouldFormat(text, msg)`, `priority` | | `CometChatUrlsFormatter` (plural) | `CometChatUrlFormatter` (singular) | | `@cometchat/uikit-shared` imports | everything imports from `@cometchat/chat-uikit-angular` | Everything in this skill imports from **`@cometchat/chat-uikit-angular`** (formatters, event classes, services) or **`@cometchat/chat-sdk-javascript`** (the `CometChat` namespace + request builders). There is no `uikit-shared` in v5. > **Verified absent in the Angular kit (v5.0.2 source):** `CometChatMessageTemplate`, `getDataSource`, `ChatConfigurator`, `DataSourceDecorator`, and `getAllMessageTemplates` do **not** exist anywhere in `projects/cometchat-uikit/src/lib` (grep over the entire library returns no matches outside specs). The web/React kit's `new CometChat.MessageTemplate(...)` / `getDataSource().getAllMessageTemplates()` pattern has **no Angular equivalent** — custom bubbles go exclusively through `MessageBubbleConfigService.setBubbleView` (Tier 3c) and message-action overrides through the `additionalOptions` / `optionsOverride` `@Input`s (Tier 3b). Do not port the React DataSource recipe here. --- ## Four-tier triage — pick the right tier before writing any code **Start with Tier 1 every time.** The Angular UI Kit follows an "inputs over components" philosophy — most additions are `@Input` bindings on already-mounted standalone components, not new components or custom code. ### Quick task → input lookup Before escalating, check whether an existing component `@Input` already does what you need (all verified in `cometchat-angular-components`): | User asks for | Likely `@Input` on which component | |---|---| | Search bar on the conversation list | `[showSearchBar]="true"` on `` | | Filter conversations | `[conversationsRequestBuilder]` on `` | | Filter messages | `[messagesRequestBuilder]` on `` | | Filter users / groups | `[usersRequestBuilder]` / `[groupsRequestBuilder]` | | Custom empty state | `[emptyView]` on list / message components | | Custom error UI | `[errorView]` | | Custom loading UI | `[loadingView]` | | Custom list row | `[itemView]` (or `[leadingView]`/`[titleView]`/`[subtitleView]`/`[trailingView]`) on list components | | Custom header subtitle | `[subtitleView]` on `` | | Hide receipts | `[hideReceipts]="true"` on `` | | Disable a message action | the matching `[hide*Option]` flag (e.g. `[hideEditMessageOption]`) on `` | | Disable mentions | `[disableMentions]="true"` on `` | | Custom send button | `[sendButtonView]` on `` | | Click handler on conversation | `(itemClick)` `@Output` on `` | | Active conversation highlight | `[activeConversation]` on `` | > **v5 hide flags ARE real on the message list** (unlike the old v4 kit, where most didn't exist). `` exposes `hideReplyInThreadOption`, `hideTranslateMessageOption`, `hideEditMessageOption`, `hideDeleteMessageOption`, `hideReactionOption`, `hideCopyMessageOption`, `hideMessageInfoOption`, `hideReplyOption`, `hideMessagePrivatelyOption`, `hideFlagMessageOption`, `hideReceipts`, `hideDateSeparator`, `hideAvatar`, and more. Prefer a `[hide*]` flag over `optionsOverride` when you just want to remove a built-in action. Confirm the exact flag in `cometchat-angular-components`. If a matching input exists, **add the binding and stop**. No new components, no custom CSS, no new files. | If they want to... | Use Tier | Cost | |---|---|---| | Hide a feature / built-in action | Tier 1 — `[hide*]` / `[hide*Option]` input | 1 line of HTML | | Replace a subsection (header, list row, empty/error/loading state, bubble footer) | Tier 1 — `[*View]` slot + `` | 1 template | | Filter what loads (only online users, joined groups, tagged conversations) | Tier 2 — `[*RequestBuilder]` | 1 builder | | Change how URLs / mentions / hashtags render inline | Tier 3a — `[textFormatters]` | Subclass of `CometChatTextFormatter` | | Add / remove / reorder message-action menu items | Tier 3b — `[additionalOptions]` / `[optionsOverride]` | `CometChatActionsIcon[]` | | Render a custom view for a message type's bubble | Tier 3c — `MessageBubbleConfigService.setBubbleView` **or** `[bubbleFooterView]` / `[appendView]` | 1 template + 1 service call | | React to kit activity (message sent, group left, conversation deleted) | Tier 4 — `CometChat*Events` | RxJS subscription | Start low. If an ask fits Tier 1 but you jumped to Tier 3, you've written 50 lines that one `[*View]` binding could have replaced. --- ## Tier 1 — Slot views (`@Input` `ng-template`) Every v5 list / message component exposes named slot-view `@Input`s that take a **`TemplateRef`**. In Angular you bind a `#ref` `` to the slot: `[itemView]="myTemplate"`. The kit passes the relevant item to the template via its `let-` context. > **Get the slot names right.** They are component-specific. The list components (``, ``, ``, ``) expose: `headerView`, `menuView`, `loadingView`, `emptyView`, `errorView`, `itemView`, `leadingView`, `titleView`, `subtitleView`, `trailingView` (conversations also has `searchView`). The message list exposes a different set: `headerView`, `footerView`, `emptyView`, `errorView`, `loadingView`, `bubbleFooterView`, `appendView`. Always confirm per component in `cometchat-angular-components`. ### 1a. Replace a list row ```typescript // app-conversations.component.ts import { Component } from "@angular/core"; import { CometChatConversationsComponent } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; import { DatePipe } from "@angular/common"; @Component({ selector: "app-conversations", standalone: true, imports: [CometChatConversationsComponent, DatePipe], template: `
{{ conversation?.getConversationWith()?.getName() }} {{ conversation?.getLastMessage()?.getSentAt() * 1000 | date: 'shortTime' }}
`, }) export class AppConversationsComponent {} ``` The `` lives **inside** the same component's template, right after the kit component — Angular resolves the `#customItem` reference and hands the `TemplateRef` to the `[itemView]` `@Input`. No `@ViewChild` is required when the template is declared inline like this. ### 1b. Replace the message-header subtitle ```html {{ user?.getStatus() === 'online' ? 'Online now' : 'Offline' }} ``` ### 1c. Custom empty / error / loading state ```html
No teammates yet.
Loading…
 ``` Keep any custom CSS to layout glue and consume `--cometchat-*` variables for colour / spacing / radius — see `cometchat-angular-theming`. --- ## Tier 2 — RequestBuilder filtering For "show a subset of X", use the matching `[*RequestBuilder]` `@Input`. The builders live on the **chat SDK** `CometChat` namespace. Never post-filter in-render with `*ngIf`. ```typescript import { CometChat } from "@cometchat/chat-sdk-javascript"; // Only conversations tagged "premium", users only conversationsRequestBuilder = new CometChat.ConversationsRequestBuilder() .setLimit(20) .setTags(["premium"]) .setConversationType("user"); // Only online users, exclude blocked usersRequestBuilder = new CometChat.UsersRequestBuilder() .setLimit(30) .setStatus(CometChat.USER_STATUS.ONLINE) .hideBlockedUsers(true); // Only groups you've joined groupsRequestBuilder = new CometChat.GroupsRequestBuilder() .setLimit(30) .joinedOnly(true); // Message list — exclude action/system messages messagesRequestBuilder = new CometChat.MessagesRequestBuilder() .setLimit(30) .setCategories(["message"]); ``` ```html ``` > Construct request builders **once** (as class properties), not inside a getter or `ngOnInit` that re-runs — a new builder instance on every change-detection pass forces the list to refetch. Confirm exact builder method names against the chat SDK; they are SDK-side, not kit-side. --- ## Tier 3 — Formatters + message-action options + per-type bubble views ### 3a. Text formatters — inline text patterns `[textFormatters]` is an `@Input` on ``, ``, and ``, taking an array of `CometChatTextFormatter` instances. **Built-in formatters** (all exported from `@cometchat/chat-uikit-angular`, all zero-arg constructors): `CometChatMentionsFormatter`, `CometChatUrlFormatter`, `CometChatEmojiFormatter`, `CometChatMarkdownFormatter`. (`CometChatTextFormatter` is the abstract base — you can't instantiate it directly.) ```typescript import { CometChatMentionsFormatter, CometChatUrlFormatter, CometChatEmojiFormatter, } from "@cometchat/chat-uikit-angular"; textFormatters = [ new CometChatMentionsFormatter(), new CometChatUrlFormatter(), new CometChatEmojiFormatter(), ]; ``` ```html ``` **⚠️ Pass the same `textFormatters` array to both list and composer.** If they differ, text renders differently while typing vs. after send. **Custom formatter — the v5 API.** Extend `CometChatTextFormatter` and implement the abstract members. This is **different from v4** — there is no `setTrackingCharacter` / `setRegexPatterns` / `getFormattedText(input)` here. v5 requires: a readonly `id`, `getRegex()`, and `format(text)`; optionally override `shouldFormat()` and set `priority` (lower runs earlier; default 100). ```typescript // hashtag-formatter.ts import { CometChatTextFormatter } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; export class HashtagFormatter extends CometChatTextFormatter { readonly id = "hashtag-formatter"; override priority = 90; getRegex(): RegExp { return /\B#(\w+)\b/g; } format(text: string): string { this.originalText = text ?? ""; this.formattedText = this.originalText.replace( this.getRegex(), '#$1' ); return this.formattedText; } // Optional — skip very short messages override shouldFormat(text: string, _message?: CometChat.BaseMessage): boolean { return !!text && text.length > 1; } } ``` ```typescript import { HashtagFormatter } from "./hashtag-formatter"; import { CometChatMentionsFormatter, CometChatUrlFormatter } from "@cometchat/chat-uikit-angular"; textFormatters = [ new CometChatMentionsFormatter(), new CometChatUrlFormatter(), new HashtagFormatter(), ]; ``` > Construct formatter instances **once** at class level (as a property), not in `ngOnInit` or a getter. Recreating them every change-detection cycle drops their internal `originalText` / `formattedText` / metadata state. ### 3b. Message-action menu — `additionalOptions` / `optionsOverride` To **add** items to the per-message action menu, pass `CometChatActionsIcon[]` to `[additionalOptions]`. To **add / remove / reorder** items with full control, pass an `[optionsOverride]` callback `(message, defaultOptions) => CometChatActionsIcon[]`. > **There is no `getMessageOptions` override point in the Angular kit** (unlike the web/React DataSource path). `getMessageOptions` exists only as an *internal* component method (`components/cometchat-message-list/cometchat-message-list.component.ts:398` → `cometchat-message-list.option-builders.ts`); the public override surface is the two `@Input`s below. Verified `@Input() additionalOptions: CometChatActionsIcon[]` (`cometchat-message-list.component.ts:174`) and `@Input() optionsOverride?: (message: CometChat.BaseMessage, defaultOptions: CometChatActionsIcon[]) => CometChatActionsIcon[]` (`cometchat-message-list.component.ts:175-178`). `CometChatActionsIcon` is exported from `@cometchat/chat-uikit-angular` (`modals/index.ts:9`) with constructor `{ id: string; title: string; iconURL: string; onClick: (id: number) => void }` (`modals/CometChatActionsIcon.ts`). A "Forward"-style action is built exactly this way — push a `CometChatActionsIcon` into `additionalOptions` (or reorder inside `optionsOverride`). ```typescript import { CometChatActionsIcon } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; // Add a "Pin" action to every message's menu additionalOptions: CometChatActionsIcon[] = [ new CometChatActionsIcon({ id: "pin", title: "Pin", iconURL: "assets/pin.svg", onClick: (id: number) => { // your pin handler — `id` is the message id }, }), ]; // Or rewrite the whole option set per message optionsOverride = ( message: CometChat.BaseMessage, defaultOptions: CometChatActionsIcon[] ): CometChatActionsIcon[] => { // e.g. drop the default options for system messages if (message.getCategory() === "action") return []; return [...defaultOptions, ...this.additionalOptions]; }; ``` ```html ``` > To merely **hide** a built-in action, prefer the Tier 1 `[hide*Option]` flag — it's a single boolean and survives kit upgrades better than reconstructing the option array. ### 3c. Custom bubble views per message type v5 has **no `CometChatMessageTemplate` and no `templates` @Input**. Two supported paths: **(i) Slot inputs on the message list** — for an extra row under existing bubbles, use `[bubbleFooterView]` (per-bubble footer) or `[appendView]` (after the bubble). Cheapest; no service. ```html {{ message?.getId() }} ``` **(ii) `MessageBubbleConfigService`** — to replace a *part* of a specific message type's bubble globally (content, header, footer, etc.), inject the service and call `setBubbleView(messageTypeKey, partMap)`. `partMap` is a `BubblePartMap` whose keys are `bubbleView` / `contentView` / `bottomView` / `footerView` / `leadingView` / `headerView` / `statusInfoView` / `replyView` / `threadView`, each a `TemplateRef` (verified `BubblePartMap` in `@cometchat/chat-uikit-angular` — `services/message-bubble-config.types.ts:30-40`). > **⚠️ The `messageTypeKey` is `"{type}_{category}"`, NOT just the type.** The kit builds its lookup key as `` `${message.getType()}_${message.getCategory()}` `` (`components/cometchat-message-bubble/cometchat-message-bubble.component.ts:322` → consumed in `getEffectiveView` at line 332). A custom message sent with `type: "poll"` has category `"custom"` (`CometChat.CATEGORY_CUSTOM`), so its key is **`"poll_custom"`** — passing just `"poll"` silently never matches and your view never renders. The kit's own internal map confirms this format (`meeting_custom`, `extension_poll_custom`, … at lines 55-75). Built-in standard types follow the same rule: text is `"text_message"`, image is `"image_message"` (service docstring `message-bubble-config.service.ts:46-58`). ```typescript import { Component, AfterViewInit, ViewChild, TemplateRef, inject } from "@angular/core"; import { CometChatMessageListComponent, MessageBubbleConfigService, } from "@cometchat/chat-uikit-angular"; @Component({ selector: "app-chat", standalone: true, imports: [CometChatMessageListComponent], template: `
{{ message?.getCustomData()?.question }}
`, }) export class AppChatComponent implements AfterViewInit { private bubbleConfig = inject(MessageBubbleConfigService); @ViewChild("pollContent") pollContent!: TemplateRef; ngAfterViewInit(): void { // Replace only the content area of the "poll" custom message type. // KEY = `${type}_${category}` → a custom message of type "poll" is category // "custom", so the key is "poll_custom" (NOT "poll" — that would never match). this.bubbleConfig.setBubbleView("poll_custom", { contentView: this.pollContent }); } } ``` `MessageBubbleConfigService` is `providedIn: 'root'`, so the config applies to every message list in the app. Call `setBubbleView` once (in `ngAfterViewInit`, after the `@ViewChild` template refs resolve). To render a genuinely new custom message type, register its `contentView` (above) **and send it through the kit** (next subsection) — not the raw SDK. ### 3d. Sending a custom message type — use the UIKit path, not the raw SDK When you create a brand-new message type (`type: "poll"`, `"location"`, …), send it with **`CometChatUIKit.sendCustomMessage(...)`**, never the raw `CometChat.sendCustomMessage(...)`. The UIKit wrapper sets `muid`, stamps the logged-in user as sender, and emits `ccMessageSent` — which is what makes the message **append** to the open list immediately. The raw SDK call skips all three, producing the two classic failures: *"Cannot determine message recipient"* (no proper sender/receiver wiring) and the realtime bubble **replacing an existing message** instead of appending (no `muid` for dedup). ```typescript import { CometChatUIKit } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; const receiverId = this.selectedUser.getUid(); // or group.getGuid() const receiverType = CometChat.RECEIVER_TYPE.USER; // or .GROUP const custom = new CometChat.CustomMessage( receiverId, receiverType, "poll", // matches the contentView type { question: "Lunch?", options: ["Yes", "No"] } ); // ✅ kit path — sets muid + sender, emits ccMessageSent → list appends await CometChatUIKit.sendCustomMessage(custom); // ❌ raw SDK — no muid/sender/event → "Cannot determine recipient" + realtime replace // await CometChat.sendCustomMessage(custom); ``` Verified: `static sendCustomMessage(message: CometChat.CustomMessage): Promise` on `CometChatUIKit` (`cometchat-uikit.ts:251`, exported from `@cometchat/chat-uikit-angular`). `CometChat.CustomMessage` has a variadic constructor (`...args: any[]`, `chat-sdk-javascript` `dist/type/lib/models/CustomMessage.d.ts:13`); the canonical 4-arg form is `(receiverId, receiverType, type, customData)`. ### 3e. Custom attachment (composer) options — the `[attachmentOptions]` input is APPENDED to the defaults `` exposes `@Input() attachmentOptions?: CometChatMessageComposerAction[]` (verified `components/cometchat-message-composer/cometchat-message-composer.component.ts:137`). **In Angular v5 this is additive, NOT a replace** — the composer first builds the default menu (image / video / audio / file / polls / collaborative doc / whiteboard, each gated by its `hide*` flag), then **appends** your options: `if ((self.attachmentOptions?.length ?? 0) > 0) o.push(...self.attachmentOptions)` (verified `cometchat-message-composer.lifecycle-utils.ts:108`). So you pass **only your custom option(s)** and the defaults are preserved automatically — do NOT reconstruct the defaults yourself. > ⚠️ This differs from the **React** kit, where the composer's `attachmentOptions` prop genuinely **replaces** the list (there you must seed from `getDataSource().getAttachmentOptions(...)`). Don't cross-port React's seed-the-defaults pattern to Angular — here it would duplicate every default option. `CometChatMessageComposerAction` is exported from `@cometchat/chat-uikit-angular` (`modals/index.ts:11`); its constructor takes `Partial` with fields `id`, `iconURL`, `title?`, `onClick: (() => void) | null` (`modals/CometChatMessageComposerAction.ts`). ```html ``` ```typescript import { CometChatMessageComposerAction } from "@cometchat/chat-uikit-angular"; // Pass ONLY your custom option — the kit keeps its defaults and appends this. locationOption = new CometChatMessageComposerAction({ id: "location", title: "Send Location", iconURL: "assets/location.svg", onClick: () => this.shareLocation(), }); ``` To only *remove* built-in options (the common ask), do **not** touch `attachmentOptions` — use the dedicated boolean inputs, which preserve everything else: `[hideImageAttachmentOption]`, `[hideVideoAttachmentOption]`, `[hideAudioAttachmentOption]`, `[hideFileAttachmentOption]`, `[hidePollsOption]`, `[hideCollaborativeDocumentOption]`, `[hideCollaborativeWhiteboardOption]`. All verified as `@Input`s on `CometChatMessageComposerComponent` (`components/cometchat-message-composer/cometchat-message-composer.component.ts:139-140`). --- ## Tier 4 — Event bus (RxJS subscriptions) Subscribe to the kit's static event classes so your own code reacts to activity inside the UI Kit. All event classes are exported from `@cometchat/chat-uikit-angular` and expose `Subject`s you `.subscribe()` to. ```typescript import { Component, OnInit, OnDestroy } from "@angular/core"; import { Subscription } from "rxjs"; import { CometChatMessageEvents, CometChatConversationEvents, CometChatGroupEvents, } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @Component({ selector: "app-root", standalone: true, template: `...` }) export class AppComponent implements OnInit, OnDestroy { private subs: Subscription[] = []; ngOnInit(): void { this.subs.push( // payload is IMessages: { message, status, parentMessageId? } CometChatMessageEvents.ccMessageSent.subscribe(({ message, status }) => { // analytics.track("message_sent", { id: message.getId(), status }); }), CometChatConversationEvents.ccConversationDeleted.subscribe( (conversation: CometChat.Conversation) => { // remove from local cache } ), CometChatGroupEvents.ccGroupLeft.subscribe((payload) => { // payload is IGroupLeft }) ); } ngOnDestroy(): void { this.subs.forEach((s) => s.unsubscribe()); } } ``` **Always unsubscribe in `ngOnDestroy`.** Angular components are destroyed on navigation; leaked subscriptions fire handlers twice. (Each event class also exposes typed `on*(cb, destroyRef?)` helpers — e.g. `CometChatMessageEvents.onMessageSent(cb, destroyRef)` — that auto-clean up when you pass a `DestroyRef`; use those if you prefer not to track `Subscription`s manually.) ### Available event streams (verified subjects) | Event class | Key subjects | |---|---| | `CometChatMessageEvents` | `ccMessageSent`, `ccMessageEdited`, `ccMessageDeleted`, `ccMessageRead`, `ccReplyToMessage`, `ccMessageTranslated` (+ low-level `onTextMessageReceived`, `onTypingStarted`, `onMessageReactionAdded`, …) | | `CometChatConversationEvents` | `ccConversationDeleted`, `ccUpdateConversation` | | `CometChatGroupEvents` | `ccGroupCreated`, `ccGroupDeleted`, `ccGroupMemberJoined`, `ccGroupLeft`, `ccGroupMemberAdded`, `ccGroupMemberScopeChanged`, `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberUnbanned`, `ccOwnershipChanged` | | `CometChatUserEvents` | `ccUserBlocked`, `ccUserUnblocked` | | `CometChatUIEvents` | `ccActiveChatChanged`, `ccOpenChat`, `ccShowOngoingCall`, `ccShowPanel`/`ccHidePanel`, `ccShowModal`/`ccHideModal`, `ccComposeMessage`, … | | `CometChatCallEvents` | call lifecycle subjects (see `cometchat-angular-calls`) | Confirm the exact subject name and payload type in the bundled `.d.ts` before subscribing — some carry typed interfaces (`IMessages`, `IGroupLeft`, `IGroupMemberJoined`, `IActiveChatChanged`, …), not raw SDK objects. --- ## Services / state-management layer The kit ships a set of injectable services (verified in `projects/cometchat-uikit/src/lib/services/`, all exported from `@cometchat/chat-uikit-angular`). Most are `providedIn: 'root'` singletons; you `inject()` them and read **signals** (snapshot, template-friendly) or **`$` Observables** (RxJS). This is the seam below the `@Input` tiers above — use it for app-wide state and cross-component coordination, not per-instance tweaks. ### `ChatStateService` — the active-chat single source of truth `providedIn: 'root'`. Holds the currently active `CometChat.User` / `CometChat.Group` / `CometChat.Conversation` and enforces **mutual exclusivity**: setting a user clears the active group and vice versa. The kit's list components (``, ``, ``) call its setters on selection, and the message components subscribe to it — so in the **service-based** wiring you place components in the template and they sync automatically with no `(itemClick)` plumbing. Each piece of state is exposed **both** as a readonly signal and as an `$` Observable: ```typescript import { Component, inject } from "@angular/core"; import { ChatStateService } from "@cometchat/chat-uikit-angular"; import { CometChat } from "@cometchat/chat-sdk-javascript"; @Component({ selector: "app-chat", standalone: true, template: ` @if (chatState.activeUser() || chatState.activeGroup()) { } `, }) export class ChatComponent { chatState = inject(ChatStateService); // signals (snapshot / template): activeUser(), activeGroup(), activeConversation() // observables: activeUser$, activeGroup$, activeConversation$ (subscribe in TS) // setters: setActiveUser(u) | setActiveGroup(g) | setActiveConversation(c) // snapshots: getActiveUser() | getActiveGroup() | getActiveChatEntity() // teardown: clearActiveChat() ← call on logout / ngOnDestroy } ``` `setActiveConversation(c)` extracts the `User` or `Group` from the conversation and delegates to the right setter. Use the **props-based** alternative (`[user]` / `[group]` `@Input`s, Tier 1 wiring) instead of the service for multi-panel layouts where each panel needs independent state. > **Don't scope `ChatStateService`** in a component's `providers: []` — it is intentionally an app-wide singleton; a local copy breaks cross-component sync. Use props for isolated panels instead. ### The customization services — concise reference All exported from `@cometchat/chat-uikit-angular`; `inject()` them. The two **search** services are `@Injectable()` (component-provided, not root) — they back the search components and you rarely inject them directly. The rest are `providedIn: 'root'`. | Service | One-liner | Key members (verified) | |---|---|---| | `MessageBubbleConfigService` | Per-type / global bubble part overrides (Tier 3c) | `setBubbleView(type, partMap)`, `setGlobalView(part, ref)`, `setGlobalViews(map)`, `setMessageTemplates(record)`, `getView(type, part)`, `clearType(type)`, `clearAll()`; `configVersion` signal + `configChanged$` | | `FormatterConfigService` | App-wide default text formatters (the `[textFormatters]` of Tier 3a, set once globally) | `getDefaultFormatters()`, `setDefaultFormatters(fmts)`, `addFormatters(fmts)`, `getFormattersWithContext(user?, alignment?)`, `resetToDefaults()` | | `CometChatTemplatesService` | SDK-wide loading / empty / error / item templates for **all** list components at once | `setSharedTemplates(t)` (all lists) + per-component `setConversationTemplates` / `setUserTemplates` / `setGroupTemplates` / `setGroupMemberTemplates` / `setCallLogTemplates` / `setMessageListTemplates` / `setSearchTemplates`; each has matching `get*` / `clear*`; `clearAllTemplates()`. Every section also exposes a `*Templates` signal + `*Templates$` Observable. Priority: component `@Input` > component-service > shared > default | | `RichTextEditorService` | Drives the rich-text composer (bold/italic/lists/links/mentions) | `createEditor(config?, el?)`, `destroyEditor(e)`, `toggleBold/Italic/Underline/Strikethrough/Code/CodeBlock/Blockquote/OrderedList/BulletList(e)`, `setLink(e, url, text?)`, `insertMention(e, id, label, n)`, `getHTML(e)` / `getText(e)` / `getTextWithMentionFormat(e)`, `undo/redo(e)`; `formatState` signal | | `SearchConversationsService` | Backs conversation search — query + live-listener state | `search(keyword, filters, builder?)`, `loadMore()`, `attachListeners(user)` / `detachListeners()`, `reset()`; `conversations`, `fetchState`, `hasMoreResults`, `typingIndicatorMap` signals | | `SearchMessagesService` | Backs message search | `search(keyword, filters, uid?, guid?, builder?, alwaysShowSeeMore?)`, `loadMore()`, `reset()`; `messages`, `fetchState`, `hasMoreResults` signals | `FormatterConfigService`, `MessageBubbleConfigService`, `CometChatTemplatesService`, and `RichTextEditorService` are the four services you *can* deliberately re-provide in a component's `providers: []` to scope a customization to one subtree (e.g. a thread panel with minimal styling) without touching the global singleton — they cross-link directly to the formatter (Tier 3a), bubble (Tier 3c), and slot-template (Tier 1) work above. > **Read signals in templates, subscribe to `$` Observables in TS.** Don't call `.subscribe()` on a signal or invoke an Observable like a function — they are distinct APIs on the same state. --- ## Recipes (common asks → right tier) ### "Filter the conversation list to just premium users" **Tier 2** — `[conversationsRequestBuilder]` with `.setTags(["premium"])`. ### "Custom empty state for the users list" **Tier 1** — `[emptyView]` slot on ``. ### "Custom row for conversations" **Tier 1** — `[itemView]` slot on ``. ### "Highlight hashtags in messages" **Tier 3a** — subclass `CometChatTextFormatter` (`id` + `getRegex()` + `format()`), pass it in `textFormatters` to list AND composer. ### "Add a 'Pin message' action to the menu" **Tier 3b** — push a `CometChatActionsIcon` into `[additionalOptions]`. ### "Remove the Translate action" **Tier 1** — `[hideTranslateMessageOption]="true"` on ``. ### "Render a custom card for our 'poll' message type" **Tier 3c** — `MessageBubbleConfigService.setBubbleView("poll_custom", { contentView: tmplRef })`. The key is `"{type}_{category}"` — a `type: "poll"` custom message is category `custom`, so the key is `poll_custom`, not `poll`. ### "When a message is sent, log it to analytics" **Tier 4** — `CometChatMessageEvents.ccMessageSent.subscribe(({ message }) => …)`. ### "When a group is deleted, navigate away" **Tier 4** — `CometChatGroupEvents.ccGroupDeleted.subscribe(group => router.navigate([...]))`. ### "Sync the active conversation across my own components" **Services** — `inject(ChatStateService)`; read `activeUser()` / `activeGroup()` signals (or `activeUser$` / `activeGroup$`), set with `setActiveConversation(c)`, clear with `clearActiveChat()`. ### "Apply one branded empty/loading state to every list at once" **Services** — `CometChatTemplatesService.setSharedTemplates({ loadingView, emptyView })`; override a single list with `setUserTemplates(...)` etc. --- ## Anti-patterns 1. **Don't reach for v4 symbols.** `CometChatMessageTemplate`, `DataSource`, `DataSourceDecorator`, `ChatConfigurator`, `CometChatThemeService`, `CometChatUrlsFormatter` (plural), and the v4 `CometChatTextFormatter` API are all **phantom in v5**. They will fail to import. 2. **Don't expect a `templates` @Input on ``.** It doesn't exist in v5. Custom bubbles go through `MessageBubbleConfigService.setBubbleView` or the `bubbleFooterView` / `appendView` slots. 3. **Don't write the v4 formatter shape.** v5 formatters need `id` + `getRegex()` + `format(text)` — not `setTrackingCharacter` / `setRegexPatterns` / `getFormattedText(input)`. 4. **Don't pass different `textFormatters` arrays** to the list and the composer — text will render inconsistently. 5. **Don't post-filter a list after render.** For "only online users", use Tier 2 `usersRequestBuilder.setStatus(...)`; don't fetch everyone and hide rows with `*ngIf`. 6. **Don't construct formatters or request builders inside a getter / `ngOnInit` that re-runs.** Build them once as class properties — recreating them per change-detection cycle drops formatter state or forces list refetches. 7. **Don't forget `ngOnDestroy` unsubscribe** (or pass a `DestroyRef` to the `on*` helpers). Leaked subscriptions double-fire after navigation. 8. **Don't add `CUSTOM_ELEMENTS_SCHEMA`** — v5 components are real Angular standalone components; import the class into `imports: []`. 9. **Don't fork or patch `@cometchat/chat-uikit-angular`.** Every customization here is achievable via Tiers 1–4. Forking breaks on kit upgrades. 10. **Don't escalate past Tier 1 without checking the catalog.** A `[hide*]` flag or a `[*View]` slot solves most asks in one line. --- ## Skill routing reference | Skill | When to route | |---|---| | `cometchat-angular-core` | Init / login / standalone setup — read first | | `cometchat-angular-components` | The `@Input`/`@Output`/slot-view reference these tiers build on | | `cometchat-angular-placement` | Where to put the customized components | | `cometchat-angular-theming` | App-wide colour / typography via CSS variables | | `cometchat-angular-features` | Out-of-the-box features (calls, extensions, AI) | | `cometchat-angular-customization` | This skill — four-tier triage + formatters / options / bubble views / events | | `cometchat-angular-production` | When customization depends on production auth | | `cometchat-angular-troubleshooting` | Formatter doesn't apply, slot renders nothing, listener fires twice | ## Sound (in-app message + call sounds) Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-angular-theming`** (Sound section). Verify the access path against the installed kit before relying on it.