cometchat-angular-customization

---
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/[email protected]` 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 `<cometchat-message-list>` | **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 `<cometchat-conversations>` |
| Filter conversations | `[conversationsRequestBuilder]` on `<cometchat-conversations>` |
| Filter messages | `[messagesRequestBuilder]` on `<cometchat-message-list>` |
| 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 `<cometchat-message-header>` |
| Hide receipts | `[hideReceipts]="true"` on `<cometchat-message-list>` |
| Disable a message action | the matching `[hide*Option]` flag (e.g. `[hideEditMessageOption]`) on `<cometchat-message-list>` |
| Disable mentions | `[disableMentions]="true"` on `<cometchat-message-composer>` |
| Custom send button | `[sendButtonView]` on `<cometchat-message-composer>` |
| Click handler on conversation | `(itemClick)` `@Output` on `<cometchat-conversations>` |
| Active conversation highlight | `[activeConversation]` on `<cometchat-conversations>` |

> **v5 hide flags ARE real on the message list** (unlike the old v4 kit, where most didn't exist). `<cometchat-message-list>` 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 + `<ng-template>` | 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` `<ng-template>` 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 (`<cometchat-conversations>`, `<cometchat-users>`, `<cometchat-groups>`, `<cometchat-group-members>`) 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: `
    <cometchat-conversations [itemView]="customItem">
    </cometchat-conversations>

    <ng-template #customItem let-conversation>
      <div class="custom-item">
        <span class="name">{{ conversation?.getConversationWith()?.getName() }}</span>
        <span class="time">{{ conversation?.getLastMessage()?.getSentAt() * 1000 | date: 'shortTime' }}</span>
      </div>
    </ng-template>`,
})
export class AppConversationsComponent {}
```

The `<ng-template>` 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
<cometchat-message-header [user]="selectedUser" [subtitleView]="customSubtitle">
</cometchat-message-header>

<ng-template #customSubtitle let-user>
  <span style="color: var(--cometchat-success-color); font-size: 12px;">
    {{ user?.getStatus() === 'online' ? 'Online now' : 'Offline' }}
  </span>
</ng-template>
```

### 1c. Custom empty / error / loading state

```html
<cometchat-users [emptyView]="noUsers" [loadingView]="spinner">
</cometchat-users>

<ng-template #noUsers><div class="empty">No teammates yet.</div></ng-template>
<ng-template #spinner><div class="loading">Loading…</div></ng-template>
```

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
<cometchat-conversations [conversationsRequestBuilder]="conversationsRequestBuilder">
</cometchat-conversations>
```

> 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 `<cometchat-message-list>`, `<cometchat-message-composer>`, and `<cometchat-message-information>`, 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
<cometchat-message-list [user]="selectedUser" [textFormatters]="textFormatters">
</cometchat-message-list>
<cometchat-message-composer [user]="selectedUser" [textFormatters]="textFormatters">
</cometchat-message-composer>
```

**⚠️ 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(),
      '<span style="color: var(--cometchat-primary-color); font-weight: 600;">#$1</span>'
    );
    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
<cometchat-message-list
  [user]="selectedUser"
  [additionalOptions]="additionalOptions"
  [optionsOverride]="optionsOverride">
</cometchat-message-list>
```

> 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
<cometchat-message-list [user]="selectedUser" [bubbleFooterView]="myFooter">
</cometchat-message-list>

<ng-template #myFooter let-message>
  <small class="bubble-meta">{{ message?.getId() }}</small>
</ng-template>
```

**(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: `
    <cometchat-message-list [user]="selectedUser"></cometchat-message-list>

    <ng-template #pollContent let-message>
      <div class="poll-card">{{ message?.getCustomData()?.question }}</div>
    </ng-template>`,
})
export class AppChatComponent implements AfterViewInit {
  private bubbleConfig = inject(MessageBubbleConfigService);
  @ViewChild("pollContent") pollContent!: TemplateRef<any>;

  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<CometChat.BaseMessage>` 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

`<cometchat-message-composer>` 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<CometChatMessageComposerAction>` with fields `id`, `iconURL`, `title?`, `onClick: (() => void) | null` (`modals/CometChatMessageComposerAction.ts`).

```html
<!-- ✅ "Send Location" is ADDED after the default photo/video/file/poll options -->
<cometchat-message-composer [attachmentOptions]="[locationOption]">
</cometchat-message-composer>
```

```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 (`<cometchat-conversations>`, `<cometchat-users>`, `<cometchat-groups>`) 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: `
    <cometchat-conversations></cometchat-conversations>
    @if (chatState.activeUser() || chatState.activeGroup()) {
      <cometchat-message-header></cometchat-message-header>
      <cometchat-message-list></cometchat-message-list>
      <cometchat-message-composer></cometchat-message-composer>
    }
  `,
})
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 `<cometchat-users>`.

### "Custom row for conversations"
**Tier 1** — `[itemView]` slot on `<cometchat-conversations>`.

### "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 `<cometchat-message-list>`.

### "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 `<cometchat-message-list>`.** 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.