Upgrading From V4 - CometChat Docs

Introduction

The CometChat v5 Angular UI Kit streamlines the integration of in-app chat functionality into your applications. Packed with prebuilt, modular UI components, it supports essential messaging features for both one-to-one and group conversations. With built-in theming options, including light and dark modes, customizable fonts, colors, and extensive configuration possibilities, developers can create chat experiences tailored to their application’s needs.

Integration

In v4, integration was straightforward due to the availability of composite components like CometChatConversationsWithMessages. This single component provided end-to-end functionality, including listing conversations, handling conversation clicks, loading messages (message header, list, composer), displaying user or group details, and supporting threaded messages. Developers could achieve all these features with minimal setup. However, customization posed significant challenges. Customizing the UI or adding custom views required a deep understanding of the internal flow of the composite component. Additionally, configurations were a mix of custom view props, behavioural props, and style props, which often led to confusion. Styling deeply nested components also proved cumbersome, limiting the developer’s ability to make meaningful changes.

With v5, composite components have been replaced with smaller, modular standalone components, such as CometChatConversations, CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer. This modular approach makes integration more flexible and easier to understand. Each component has a well-defined purpose, allowing developers to use them in ways that suit their specific requirements. The need for complex configurations has been eliminated, as developers can now customize behavior and styling directly via CSS variables and Angular template projections. Styling has been significantly simplified, with every component carefully assigned thoughtful CSS class names following BEM methodology, enabling developers to customize styles globally or at the component level effortlessly. To support the transition from v4 to v5, CometChat has built a sample app that replicates the functionality of v4’s composite components. This sample app serves as a reference for developers looking to build additional features such as user/group details, call log details, threaded messages, and advanced messaging capabilities. By following this approach, developers can take full advantage of v5’s modular design while implementing complex functionality in an organized manner.

Learn how to build a complete messaging UI using the v5 UI Kit by following the step-by-step guide here.

Components

The v4 UI Kit provided composite components like CometChatConversationsWithMessages, which offered end-to-end functionality. These components integrated features such as conversation lists, message views (header, list, composer), user/group details, and threaded messages into a single unit. However, customization of deeply nested components through configuration was challenging and resulted in a suboptimal developer experience.

Components in v4 UI Kit:
CometChatConversationsWithMessages	CometChatUsersWithMessages	CometChatGroupsWithMessages
CometChatMessages	CometChatMessageHeader	CometChatMessageList
CometChatMessageComposer	CometChatThreadedMessages	CometChatConversations
CometChatUsers	CometChatGroups	CometChatContacts
CometChatDetails	CometChatGroupMembers	CometChatAddMembers
CometChatBannedMembers	CometChatTransferOwnership	CometChatMessageInformation
CometChatIncomingCall	CometChatOngoingCall	CometChatOutgoingCall
CometChatCallButtons	CometChatCallLogs	CometChatCallLogDetails
CometChatCallLogHistory	CometChatCallLogRecordings	CometChatCallLogParticipants
CometChatCallLogsWithDetails	CometChatUserMemberWrapper

In v5, the composite approach is replaced with smaller, modular standalone components like CometChatConversations, CometChatMessageHeader, CometChatMessageList, and CometChatMessageComposer. Developers now stitch these components together to build the desired functionality. This change allows for greater flexibility and easier customization, significantly improving the developer experience while maintaining functionality.

Components in v5 UI Kit:
CometChatConversations	CometChatUsers	CometChatGroups
CometChatGroupMembers	CometChatMessageHeader	CometChatMessageList
CometChatMessageComposer	CometChatThreadHeader	CometChatIncomingCall
CometChatOutgoingCall	CometChatOngoingCall	CometChatCallButtons
CometChatCallLogs	CometChatSearch	CometChatMessageInformation
CometChatConversationStarter	CometChatSmartReplies	CometChatConversationSummary

Theming

In v4, theming was managed using the CometChatThemeService, an injectable Angular service with two key properties: Palette and Typography. The Palette property provided methods like setPrimary(), setAccent(), and setMode() for configuring colors and themes. The Typography property provided methods like setFontFamily() and setFontWeightBold() for configuring text styles. Developers injected this service in their component constructors and called setter methods to customize the appearance. While this approach worked, it introduced several challenges. Customizing themes required programmatic interaction with the service in every component that needed theming. Switching between light and dark modes required calling setMode() on the palette. Per-component styling required passing dedicated style objects (like ConversationsStyle, AvatarStyle, ListItemStyle) as inputs, which was verbose and hard to maintain across large applications.

app.component.ts

import { Component } from '@angular/core';
import { CometChatThemeService } from '@cometchat/chat-uikit-angular';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html'
})
export class AppComponent {
  constructor(private themeService: CometChatThemeService) {
    themeService.theme.palette.setMode("light");
    themeService.theme.palette.setPrimary({ light: "#6851D6", dark: "#6851D6" });
    themeService.theme.palette.setAccent({ light: "#6851D6", dark: "#6851D6" });
  }
}

In v5, theming has been completely revamped. The older CometChatThemeService and style object system have been replaced with modern CSS variables. This means every design token — colors, spacing, typography — is now represented as a CSS variable. Changing the primary color is as simple as updating a CSS variable; no need to interact with complex theming logic or inject services. The use of CSS variables makes styling declarative and lightweight, enhancing both performance and developer experience. To ensure consistency and scalability, the new theming system adheres to the BEM (Block Element Modifier) methodology for class naming. The new theming approach enables developers to style components either globally or at a component-specific level with precision. For example, applying a unique style to a particular element within a component or globally is now straightforward. This move to CSS variables and thoughtful class naming marks a significant improvement in theming flexibility and simplicity.

styles.css

@import '@cometchat/chat-uikit-angular/styles/css-variables.css';

.cometchat {
  --cometchat-primary-color: #f76808;
  --cometchat-neutral-color-300: #ffffff;
  --cometchat-background-color-03: #feede1;
}

@media (prefers-color-scheme: dark) {
  .cometchat {
    --cometchat-primary-color: #f76808;
    --cometchat-neutral-color-300: #311502;
    --cometchat-background-color-03: #451d02;
  }
}

app.component.ts

import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  standalone: true,
  template: `
    <div class="cometchat-root" [attr.data-theme]="theme">
      <!-- Your chat components here -->
    </div>
  `
})
export class AppComponent implements OnInit {
  theme = 'light';

  ngOnInit(): void {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    this.theme = mediaQuery.matches ? 'dark' : 'light';
    mediaQuery.addEventListener('change', (e) => {
      this.theme = e.matches ? 'dark' : 'light';
    });
  }
}

For detailed guidance on theming and customizing colors in the CometChat Angular UI Kit, refer to the following resources:

Theming Documentation: Guide to Theming

Properties

In v5, the approach to properties has been significantly refined to improve clarity and ease of use. All style-related inputs — previously used to customize components via style objects like ConversationsStyle, AvatarStyle, ListItemStyle, BadgeStyle, DateStyle, and StatusIndicatorStyle — have been replaced by a more efficient and native theming system based on CSS variables. This change ensures a seamless and flexible styling process without the need for verbose or redundant configuration within the component inputs. Configuration inputs, which were prominent in v4, have also been eliminated. With v5’s modular design, components are no longer nested inside composite wrappers, making such configurations unnecessary. Developers now have direct control over each component, reducing complexity and increasing flexibility in how components are used and styled. Custom view inputs have undergone a comprehensive overhaul to ensure consistency across all components. For example, components that are represented as list items now share a uniform set of customizable template inputs, enabling a standardized approach to customization. These inputs include itemView, leadingView, trailingView, subtitleView, and titleView. This consistent naming convention makes it easier for developers to understand and apply customizations across various components, streamlining the development process. Event naming has also been standardized. In v4, events were callback function inputs with an on prefix (e.g., [onItemClick]="handler"). In v5, events are proper Angular @Output() EventEmitters without the on prefix (e.g., (itemClick)="handler($event)"). This aligns with Angular conventions and provides better IDE support.

v4 Event Pattern	v5 Event Pattern
`[onItemClick]="handleItemClick"`	`(itemClick)="handleItemClick($event)"`
`[onSelect]="handleSelect"`	`(select)="handleSelect($event)"`
`[onError]="handleError"`	`(error)="handleError($event)"`
`[onBack]="handleBack"`	`(backClick)="handleBack()"`
`[onThreadRepliesClick]="handleThread"`	`(threadRepliesClick)="handleThread($event)"`

Shared Dependencies

In v4, the Angular UI Kit relied on three shared packages: @cometchat/uikit-resources, @cometchat/uikit-elements, and @cometchat/uikit-shared, designed to provide common functionality and resources across the Web UI Kits (React, Angular, Vue). While these shared packages promoted code reuse, they came with significant drawbacks. One major issue was the reliance on web components in the uikit-elements and uikit-shared packages. This required the use of CUSTOM_ELEMENTS_SCHEMA in every Angular module that used CometChat components. Styling web components via CSS was inherently restrictive, often requiring additional effort to achieve desired results. Furthermore, the web component layer added complexity to Angular’s change detection and made debugging more difficult. IDE support for web component attributes was also limited, reducing developer productivity.

// v4: Required CUSTOM_ELEMENTS_SCHEMA and peer dependencies
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { CometChatConversations } from '@cometchat/chat-uikit-angular';
import "@cometchat/uikit-elements"; // Required side-effect import

@NgModule({
  imports: [CometChatConversations],
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Required for web components
})
export class AppModule {}

In v5, these challenges have been addressed with a complete shift to pure Angular standalone components. The dependency on shared web component packages has been removed entirely, enabling seamless integration with Angular’s ecosystem. Pure Angular components eliminate limitations around styling, allowing developers to leverage modern CSS techniques without restrictions. They also provide native Angular behavior — proper @Input() and @Output() bindings, full TypeScript type checking, and complete IDE autocompletion support — significantly enhancing the development experience.

// v5: No CUSTOM_ELEMENTS_SCHEMA, no peer dependencies, full type safety
import { Component } from '@angular/core';
import {
  CometChatConversationsComponent,
  CometChatMessageListComponent,
  CometChatMessageComposerComponent
} from '@cometchat/chat-uikit-angular';

@Component({
  selector: 'app-chat',
  standalone: true,
  imports: [
    CometChatConversationsComponent,
    CometChatMessageListComponent,
    CometChatMessageComposerComponent
  ],
  template: `
    <cometchat-conversations (itemClick)="onSelect($event)"></cometchat-conversations>
    <cometchat-message-list></cometchat-message-list>
    <cometchat-message-composer></cometchat-message-composer>
  `
})
export class ChatComponent {
  onSelect(conversation: any): void { }
}

This architectural redesign simplifies the UI Kit, aligns it with Angular best practices, and makes it more intuitive and extensible for developers. By resolving the limitations of v4, the v5 UI Kit offers a more streamlined, flexible, and productive environment for building modern applications.

State Management

In v4, developers had to pass [user] or [group] inputs to every component that needed to know about the active conversation. This meant repeating the same binding across cometchat-message-header, cometchat-message-list, and cometchat-message-composer — leading to boilerplate and potential sync issues.

// v4: Pass user/group to every component manually
<cometchat-message-header [user]="selectedUser"></cometchat-message-header>
<cometchat-message-list [user]="selectedUser"></cometchat-message-list>
<cometchat-message-composer [user]="selectedUser"></cometchat-message-composer>

In v5, a new ChatStateService provides centralized state management. Set the active conversation once, and all downstream components automatically react to the change — no prop drilling required. Props still work and take priority when provided, giving developers the flexibility to override shared state for specific instances.

// v5: Set once, all components react
import { ChatStateService } from '@cometchat/chat-uikit-angular';

@Component({
  template: `
    <cometchat-conversations (itemClick)="onConversationClick($event)"></cometchat-conversations>
    <!-- These auto-subscribe to ChatStateService -->
    <cometchat-message-header></cometchat-message-header>
    <cometchat-message-list></cometchat-message-list>
    <cometchat-message-composer></cometchat-message-composer>
  `
})
export class ChatComponent {
  constructor(private chatState: ChatStateService) {}

  onConversationClick(conversation: any): void {
    this.chatState.setActiveConversation(conversation);
  }
}

For detailed guidance on state management patterns, refer to the State Management Guide and the ChatStateService API Reference.

Localization

Both v4 and v5 use a built-in CometChatLocalize class for localization — no external libraries are required. The API has been slightly updated in v5 with method renames and expanded language support (19 languages, up from 12).

v4 Method	v5 Method
`CometChatLocalize.setLocale("hi")`	`CometChatLocalize.setCurrentLanguage("hi")`
`CometChatLocalize.getLocale()`	`CometChatLocalize.getCurrentLanguage()`
`CometChatLocalize.init()`	Not needed — auto-initializes

v5 also introduces a translate pipe for use directly in templates:

<span>{{ 'SEND_MESSAGE' | translate }}</span>

Documentation Index

​Introduction

​Integration

​Components

​Theming

​Properties

​Shared Dependencies

​State Management

​Localization

​Quick Migration Checklist

Introduction

Integration

Components

Theming

Properties

Shared Dependencies

State Management

Localization

Quick Migration Checklist