Upgrading from V5 to V6

Migration guide for upgrading from CometChat React UI Kit v5 to v6 with breaking changes and new patterns.

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.

---