Upgrading from V5 to V6 - CometChat Docs

AI Integration Quick Reference

Field	Value
Package	`@cometchat/chat-uikit-react` (replaces v5 packages)
New init pattern	`UIKitSettingsBuilder` + `CometChatUIKit.init()`
Theming	CSS variables replace inline style objects. See Theming
Localization	`CometChatLocalize.init(settings)` — language codes changed (e.g., `en` → `en-US`), new `CalendarObject` for date formatting
Key changes	`setLocale` → `setCurrentLanguage`, `localize` → `getLocalizedString`, `datePattern` → `CalendarObject`-based props

The CometChat v6 React UI Kit introduces a revamped localization system with enhanced support for language management, date formatting, and missing key handling. This guide outlines the key differences and provides a step-by-step migration process from v5 to v6.

Overview of Changes

Feature	v5	v6
Initialization	Used `init(language, resources)` with separate params.	Uses `init(settings: LocalizationSettings)` with a configuration object.
Translation Management	Manually updated translations using `resources`.	Uses `translationsForLanguage` in `init()` and `addTranslation()`.
Language Codes	Used shorthand codes (e.g., `en`, `fr`).	Uses full language-region codes (e.g., `en-US`, `fr`).
Date & Time Localization	Not configurable.	Supports `CalendarObject` for date formatting.
Timezone Handling	Not available.	Introduced `timezone` setting.
Missing Key Handler	Not available.	Introduced `missingKeyHandler` to handle missing translations.

CometChatLocalize

Initialization

In CometChat v5 UI Kit, the CometChatLocalize.init() accepts 2 parameters: language & resources

V5 UI Kit

CometChatLocalize.init("en", {
  CHATS: "Chats",
});

In CometChat v6 UI Kit, the CometChatLocalize.init() method accepts a localization setting instead of individual parameters.

V6 UI Kit

CometChatLocalize.init({
  language: "en-US",
  translationsForLanguage: {
    "en-US": { conversation_chat_title: "Chats" },
  },
  disableAutoDetection: false,
  disableDateTimeLocalization: false,
  timezone: "Europe/Madrid",
  calendarObject: new CalendarObject({
    today: "hh:mm A",
    yesterday: "[Yesterday]",
    otherDays: "DD MMM YYYY, hh:mm A",
    relativeTime: {
      minute: "%d minute ago",
      minutes: "%d minutes ago",
      hour: "%d hour ago",
      hours: "%d hours ago",
    },
  }),
  missingKeyHandler: (key) => `Missing translation: ${key}`,
});

Language Code Changes

In CometChat v5 UI Kit, the language code for English was en. In CometChat v6 UI Kit, the language codes have been expanded to distinguish between regional variants:

en-US for American English
en-GB for British English

There are no changes for any other languages.

Managing Translations

In CometChat v5 UI Kit, the only way to add or override translations was by passing them in the init() method.

V5 UI Kit

CometChatLocalize.init("en", {
  CHATS: "Chats",
});

In CometChat v6 UI Kit, translations can be added or overridden using the init() method or the addTranslation() method.

V6 UI Kit

CometChatLocalize.addTranslation({
  "en-US": { conversation_chat_title: "Chats" },
});

Handling Date & Time Localization

CometChat v5 UI Kit lacked support for date formatting, but CometChat v6 UI Kit introduces the CalendarObject for date and time formatting.

V6 UI Kit

const formattedDate = new CalendarObject({
  today: "[Today at] hh:mm A",
  yesterday: "[Yesterday at] hh:mm A",
  otherDays: "DD MMM YYYY, hh:mm A",
});
CometChatLocalize.init({
  calendarObject: formattedDate,
});

Handling Missing Translation Keys

CometChat v5 UI Kit did not handle missing translation keys, whereas CometChat v6 UI Kit introduces a missingKeyHandler for better control.

V6 UI Kit

CometChatLocalize.init({
  missingKeyHandler: (key) => `Missing translation: ${key}`,
});

Migrating JSON Translation Files

In CometChat v5 UI Kit, the language code for English was en.

V5 UI Kit

{
  "en": {
    "CHATS": "Chats"
  }
}

In CometChat v6 UI Kit, the language codes have been expanded to distinguish between regional variants: en-US & en-GB.

V6 UI Kit

{
  "en-US": {
    "conversation": "conversation_chat_title"
  }
}

Make sure your JSON translation files follow the new format.

Additional Resources

CometChatLocalize Class

View the source code for the localization class.

Language JSON Files

Browse all available language translation files.

Property Changes

In CometChat v6 UI Kit, several props and methods in components and the CometChatLocalize class have been updated. Below is a detailed reference of renamed, added, and removed properties and methods.

Conversations

New Properties

Name	Type	Description
lastMessageDateTimeFormat	CalendarObject	Format for displaying the timestamp of the last message in the conversations list.

Removed Properties

Name	Type	Description
datePattern	DatePatterns	Format for displaying the timestamp of the last message in the conversations list.

Message Header

New Properties

Name	Type	Description
lastActiveAtDateTimeFormat	CalendarObject	Format for displaying the “last active” timestamp in the message header.

Message List

New Properties

Name	Type	Description
separatorDateTimeFormat	CalendarObject	Format for the date separators in the message list.
stickyDateTimeFormat	CalendarObject	Format for sticky date headers displayed in the message list.
messageSentAtDateTimeFormat	CalendarObject	Format for the timestamp displayed next to messages.
messageInfoDateTimeFormat	CalendarObject	Format for timestamps displayed in message details (e.g., delivery or read time).

Removed Properties

Name	Type	Description
datePattern	DatePatterns	Format for the date separators & sticky date in the message list.
timePattern	DatePatterns	Format for the timestamp displayed next to messages.

Thread Header

New Properties

Name	Type	Description
separatorDateTimeFormat	CalendarObject	Format for the date separators.
messageSentAtDateTimeFormat	CalendarObject	Format for the timestamp displayed next to messages.

Call Logs

New Properties

Name	Type	Description
callInitiatedDateTimeFormat	CalendarObject	Format for displaying the call initiation time in call logs.

Removed Properties

Name	Type	Description
datePattern	DatePatterns	Format for rendering dates in the call logs.

CometChatLocalize Class

New Methods

Name	Description
addTranslation	Adds custom translations to the default translations.
getDefaultLanguage	Returns the default language.
getDateLocaleLanguage	Returns the language used for date localization.
formatDate	Formats a timestamp based on the provided calendar configuration.

Renamed Methods

Name	Description	Old Name
getCurrentLanguage	Gets the current language.	getLocale
setCurrentLanguage	Sets the current language.	setLocale
getLocalizedString	Localizes the given string based on the active language.	localize

Removed Methods

Name	Description
getLanguageCode	Returns the language code of current language.
setDefaultLanguage	Sets the default language if no language is passed in init method.
isRTL	Returns true if the active language is rtl otherwise return false.
getDir	Returns `rtl` or `ltr` based on the active language.

Next Steps

React.js Integration

Fresh v6 setup guide for React.js.

Components Overview

Explore all v6 prebuilt UI components.

Theme

New CSS variable-based theming system.

Methods

Init, login, logout, and other UI Kit methods.

​Overview of Changes

​CometChatLocalize

​Initialization

​Language Code Changes

​Managing Translations

​Handling Date & Time Localization

​Handling Missing Translation Keys

​Migrating JSON Translation Files

​Additional Resources

CometChatLocalize Class

Language JSON Files

​Property Changes

​Conversations

​New Properties

​Removed Properties

​Message Header

​New Properties

​Message List

​New Properties

​Removed Properties

​Thread Header

​New Properties

​Call Logs

​New Properties

​Removed Properties

​CometChatLocalize Class

​New Methods

​Renamed Methods

​Removed Methods

​Next Steps

React.js Integration

Components Overview

Theme

Methods

Overview of Changes

CometChatLocalize

Initialization

Language Code Changes

Managing Translations

Handling Date & Time Localization

Handling Missing Translation Keys

Migrating JSON Translation Files

Additional Resources

Property Changes

Conversations

New Properties

Removed Properties

Message Header

New Properties

Message List

New Properties

Removed Properties

Thread Header

New Properties

Call Logs

New Properties

Removed Properties

CometChatLocalize Class

New Methods

Renamed Methods

Removed Methods

Next Steps