> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading from V5 to V6

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

<Accordion title="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](/ui-kit/react/v6/theme) |
  | 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 |
</Accordion>

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()`](/ui-kit/react/v5/localize#methods) accepts 2 parameters: `language` & `resources`

```js title="V5 UI Kit" lines theme={null}
CometChatLocalize.init("en", {
  CHATS: "Chats",
});
```

In CometChat v6 UI Kit, the [`CometChatLocalize.init()`](/ui-kit/react/v6/localize#initialize-cometchatlocalize) method accepts a [localization setting](/ui-kit/react/v6/localize#localizationsettings) instead of individual parameters.

```js title="V6 UI Kit" lines theme={null}
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()`](/ui-kit/react/v5/localize#methods) method.

```js title="V5 UI Kit" lines theme={null}
CometChatLocalize.init("en", {
  CHATS: "Chats",
});
```

In CometChat v6 UI Kit, translations can be added or overridden using the [`init()`](/ui-kit/react/v6/localize#initialize-cometchatlocalize) method or the [`addTranslation()`](/ui-kit/react/v6/localize#add-custom-translations) method.

```js title="V6 UI Kit" lines theme={null}
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`](/ui-kit/react/v6/localize#calendarobject) for date and time formatting.

```js title="V6 UI Kit" lines theme={null}
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`](/ui-kit/react/v6/localize#initialize-cometchatlocalize) for better control.

```javascript title="V6 UI Kit" lines theme={null}
CometChatLocalize.init({
  missingKeyHandler: (key) => `Missing translation: ${key}`,
});
```

***

### Migrating JSON Translation Files

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

```json title="V5 UI Kit" lines theme={null}
{
  "en": {
    "CHATS": "Chats"
  }
}
```

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

```json title="V6 UI Kit" lines theme={null}
{
  "en-US": {
    "conversation": "conversation_chat_title"
  }
}
```

Make sure your JSON translation files follow the new format.

***

## Additional Resources

<CardGroup cols={2}>
  <Card title="CometChatLocalize Class" icon="code" href="https://github.com/cometchat/cometchat-uikit-react/blob/v6/src/resources/CometChatLocalize/cometchat-localize.ts">
    View the source code for the localization class.
  </Card>

  <Card title="Language JSON Files" icon="language" href="https://github.com/cometchat/cometchat-uikit-react/tree/v6/src/resources/CometChatLocalize/resources">
    Browse all available language translation files.
  </Card>
</CardGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="React.js Integration" href="/ui-kit/react/v6/react-js-integration">
    Fresh v6 setup guide for React.js.
  </Card>

  <Card title="Components Overview" href="/ui-kit/react/v6/components-overview">
    Explore all v6 prebuilt UI components.
  </Card>

  <Card title="Theme" href="/ui-kit/react/v6/theme">
    New CSS variable-based theming system.
  </Card>

  <Card title="Methods" href="/ui-kit/react/v6/methods">
    Init, login, logout, and other UI Kit methods.
  </Card>
</CardGroup>

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.