> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade the CometChat Widget from v1 to v2

> What changes when you move your embed from the v1 widget to v2, and the four things to check before you do.

Version 2 of the Chat Widget is a new rendering engine with the same JavaScript API. Your existing
integration code keeps working — what changes is the markup the widget produces, and which features a
variant starts with.

<Note>
  **Nothing happens until you choose it.** `@latest` and a bare package name still install v1, so an
  embed you do not touch keeps running v1 exactly as it does today.
</Note>

## 1. Point the script tag at v2

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@2.x.x/dist/main.js"></script>
```

That is the only required change for most integrations. Every method and configuration field keeps
its name, and two behaviours changed — see [what stays the same](#4-what-does-not-change).

<Note>
  **Using the WordPress plugin?** Skip this step — the plugin loads its own copy of the widget and
  updates on its own schedule. Steps 2 and 3 still apply to you.
</Note>

## 2. Create a new variant for the features v2 adds

Variants created before v2 carry no setting for the five features v2 added. Rather than guess, the
widget leaves them **off**, so upgrading never switches something on in your chat that you did not
choose.

That means an existing variant renders v2 without:

* Pinned messages
* Saved messages
* Pinned conversations
* Thread subscription
* Multiple attachments

**To get them, create a new variant** in the Widget Builder — new variants start with the full v2
feature set. An existing variant cannot be switched over, so the builder does not offer these five
settings on one.

Everything else your variant configures — layout, colours, fonts, tabs, the docked button — carries
over untouched, and every feature your variant already had keeps working.

## 3. Check your custom CSS and JavaScript

This is the part most likely to need work, and the only one that can change how your widget looks
without any error appearing.

**v2 renames most CSS classes.** If you added **Custom CSS** in the Widget Builder's Custom Code
panel, rules written against v1 class names will no longer match, and those styles will silently stop
applying. Check your rules against the class names in the
[UI Kit documentation](/docs/ui-kit/react/overview), which is what v2 renders.

**Custom JavaScript fails more loudly.** Code that looked elements up by a v1 class name now gets
`null` back, so a script that worked before may throw instead of quietly doing nothing. Check any
`querySelector` or `getElementsByClassName` call that targets a CometChat element.

CSS variables changed too — some `--cometchat-*` names from v1 no longer exist. Any rule that sets
one that was removed has no effect.

## 4. What does not change

The entire JavaScript API, verified call by call:

`CometChatAuth.start` · `init` · `login` · `logout` · `launch` · `chatWithUser` · `chatWithGroup` ·
`callUser` · `callGroup` · `uiEvent` · `localize` · `createOrUpdateUser` · `createOrUpdateGroup` ·
`showDockedUnreadCount` · `showGroupActionMessages`

Every configuration field keeps its name, and the embed snippet has the same shape. Two behaviours
did change — check these if your integration relies on either:

| Field | v1 | v2 |
| - | - | - |
| `isDocked` omitted from `start()` | always docked | follows the variant's docked setting |
| `launch()` with no `height` | the browser's default iframe height | `100%` of the mount, so give the mount a height |

Otherwise, if your integration only calls the API and passes configuration, step 1 is the whole
upgrade.

## 5. Going back to v1

Pin the last v1 build:

```html theme={null}
<script defer src="https://cdn.jsdelivr.net/npm/@cometchat/chat-embed@1.0.36/dist/main.js"></script>
```

Your variant is unaffected by the version you load, so switching back needs no other change.

## Checklist

<Steps>
  <Step title="Update the script tag">`@1.x.x` → `@2.x.x`, unless you use the WordPress plugin.</Step>
  <Step title="Create a new variant">Only if you want the five features v2 adds.</Step>
  <Step title="Re-check custom CSS">Rules written against v1 class names will not match.</Step>
  <Step title="Re-check custom JavaScript">Selectors that targeted v1 class names now return `null`.</Step>
</Steps>


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