CometChat UI Kit for React
The CometChat React UI Kit provides pre-built, customizable UI components that developers can use to quickly integrate real-time messaging and calling into any React application.
🚀 Explore the Sample App
Check out the Sample App to see the UI Kit in action with a fully functional chat experience including conversations, messaging, calling, and AI features.
Prerequisites
- Node.js >= 18
- npm >= 9
- React >= 18
Getting Started
- Register at the CometChat Dashboard to create an account.
- Create a new app to get your App ID, Region, and Auth Key.
Installation
npm install @cometchat/chat-uikit-react
Integrate with AI Coding Agents
CometChat Agent Skills teach your AI coding agent how to build with the CometChat React UI Kit in React 18+ apps built with Vite, Create React App, Next.js, React Router, or Astro. Ask your agent to “add chat to my app” and it detects your project setup, walks you through a short plan for your approval, and then writes the integration code directly into your existing app, following the official CometChat guides. The skills work with Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and other popular coding agents.
Run the installer in your project root (requires Node.js 18+):
npx @cometchat/skills add
The skills are installed for Claude Code by default; pass --ide <agent> (for example, --ide cursor) to install them for a different agent. Then open your project in your agent and prompt it with “add chat to my app”, or run /cometchat.
To learn more, visit CometChat Agent Skills.
Features
- Conversations — List and manage one-on-one and group chats
- Messages — Rich message list with reactions, threads, and read receipts
- Calling — Voice and video calling with call logs
- AI Features — AI-powered assistant chat and smart replies
- Theming — CSS custom properties for full visual customization
- Localization — Built-in multi-language support
Testing
The project has three test suites: unit tests (Vitest), E2E tests (Playwright), and Storybook.
Unit Tests (Vitest)
Unit tests live alongside the source files as *.spec.ts / *.spec.tsx and cover individual components, hooks, and utilities.
Run all unit tests (single pass):
npm test
Run with coverage:
npm run test:coverage
No browser or running server is required.
Storybook
Storybook provides an interactive development environment for building and testing components in isolation.
Start Storybook (dev mode):
npm run storybook
Opens at http://localhost:6006.
Build static Storybook:
npm run build-storybook
E2E Tests (Playwright)
End-to-end tests live in sample-app/e2e/ and run against the live sample app and a real CometChat app. They cover full user journeys: login, messaging, attachments, reactions, threads, pin & save, groups, calls, search, AI, and more.
Prerequisites
1. Create a CometChat App
Create a new CometChat app dedicated to E2E testing — the suite creates and deletes e2e-* users and groups, so don’t point it at an app with real data.
In the CometChat Dashboard, enable:
- Stickers — and add sticker packs from its settings (the sticker tests need at least one pack)
- Calling
- Conversation & Advanced Search
- Polls
- Collaborative Document
- Collaborative Whiteboard
Then, under Chat & Messaging → Settings → General Configuration → Media URL Access, select Presigned URLs.
Required for every attachment flow — e2e/multi-attachment, the e2e/message-composer attachment tests, and the image test in e2e/thread-subscription. Without it the upload tray never resolves and those tests time out.
3. Create the AI Agent Users
In the Dashboard → BYO Agents:
- AI assistant chat: UID
ai-agent-e2e or mention it in AI_AGENT_UID, name AI Agent E2E, role @agentic.
- Agentic group chat: two more
@agentic users; put their UIDs in GROUP_AGENT_1_UID / GROUP_AGENT_2_UID. The agents must be connected to a backend that actually replies — the agentic-group tests wait for a real reply.
cd sample-app
cp .env.e2e.example .env.e2e
Fill in .env.e2e:
COMETCHAT_APP_ID=your-app-id
COMETCHAT_REGION=us
COMETCHAT_AUTH_KEY=your-auth-key
COMETCHAT_API_KEY=your-rest-api-key
AI_AGENT_UID=ai-agent-e2e
.env.e2e.example documents every variable the suite reads. The optional ones only enable specific tests:
| Var |
Suite |
E2E_BLOCKED_MIME_TYPE |
multi-attachment (blocked-MIME test) |
E2E_PIN_MESSAGES_LIMIT |
pin & save (pin-limit test, see below) |
GROUP_AGENT_1_UID, GROUP_AGENT_2_UID, AGENTIC_GROUP_1_ID, AGENTIC_GROUP_2_ID |
agentic group chat |
At the start of every run the suite prints any variable that is missing and which tests it will skip.
5. Install Dependencies and Playwright Browsers
The sample app can run against your local UI Kit source (src/) instead of the published package, which needs both installs:
npm ci # repo root — the UI Kit's own dependencies
cd sample-app && npm ci # the sample app
npx playwright install chromium
Running E2E Tests
Seed test data (idempotent — safe to re-run):
cd sample-app
npm run e2e:seed
Run all E2E tests (headless):
UIKIT_LOCAL=1 npm run e2e
UIKIT_LOCAL=1 makes the sample app resolve @cometchat/chat-uikit-react from ../src, so the tests exercise your local changes. Without it they run against the published package in sample-app/node_modules. On Windows (or to make it permanent) put UIKIT_LOCAL=1 in sample-app/.env instead.
Playwright starts the dev server on http://localhost:3005 by itself (and reuses one you already have running), so there is no need to start it in a separate terminal. To use another port, set E2E_PORT together with a server command for that port (e.g. E2E_PORT=3006 E2E_WEB_SERVER_COMMAND="npx vite --port 3006 --strictPort").
Run against a production build — what end users get, and slower to start:
UIKIT_LOCAL=1 npm run build -- --sourcemap
E2E_WEB_SERVER_COMMAND="npx vite preview --port 3005 --strictPort" npm run e2e
Other modes:
npm run e2e:ui # Playwright UI (interactive)
npm run e2e:headed # visible browser
npm run e2e:debug # step through
npx playwright test e2e/conversations/conversations.spec.ts # one spec file
npx playwright test --grep "pin" # tests whose title matches
npx playwright test --grep @smoke # the core-flow smoke subset (~10 min)
Accessibility: e2e/accessibility/axe.spec.ts scans the main screens with axe (WCAG 2.0/2.1 A and AA). Violations that exist today are listed per screen in e2e/accessibility/axe-baseline.json; the scan fails only on new ones. After fixing a violation, remove its rule from the baseline. To regenerate the baseline from the current app (review the diff before committing): UPDATE_AXE_BASELINE=1 npx playwright test e2e/accessibility.
Lint the suite: npm run lint:e2e (eslint-plugin-playwright — prefer web-first assertions such as await expect(locator).toBeVisible() over fixed waitForTimeout sleeps). locator.isVisible() does not wait, so it is a lint error when given a timeout; use toBeVisible({ timeout }), or visibleWithin() from e2e/helpers/wait.ts for an optional element.
Results: the HTML report is written to playwright-report/ (npx playwright show-report), a machine-readable summary to e2e-results/results.json, and traces/screenshots of failures to test-results/.
Cleanup
To delete all E2E-created data and reset the app:
npm run e2e:cleanup
Test Data Strategy
| Chat / user |
Purpose |
Modified by Tests? |
| Alice Johnson (e2e-user-1) |
The logged-in test user |
— |
| Bob Smith (e2e-user-2) |
Static 1:1 — read-only tests; the participant in Strategy |
❌ Never |
| Design Team (e2e-group-1) |
Static group — pagination, group details |
❌ Never |
| Strategy (e2e-group-35) |
Mutable group — send/edit/delete/thread/reactions/pin |
✅ Yes |
| CI/CD (e2e-group-33) |
Incoming messages for message-privately / pin-conversation tests |
❌ Never - Unless the tests send incoming messages |
| Engineering |
Mutable group — the chat the pin-conversation tests pin/unpin |
✅ Yes |
| Testing |
Secondary mutable group — use for anything (currently the pin-conversation “stays below pinned” test) |
✅ Yes |
| AI Agent E2E |
AI assistant chat tests |
✅ Yes |
| Perf User (perf-user-1) |
A stable login for performance measurement; created by the seed, never deleted by cleanup |
❌ Never |
| Charlie Brown (e2e-user-3), Diana Prince (e2e-user-4) |
Caller and callee in the incoming-call tests; members of the agentic groups; Charlie also logs in during the switch-user journey |
✅ Call logs grow — don’t assert on their call history |
| Other seeded users (e2e-user-5 … e2e-user-35) and groups (e2e-group-2 … e2e-group-34) |
Population for lists, search, pagination and member counts |
❌ Never |
AI Solo E2E, AI Squad E2E (e2e-agentic-group-1/2, or AGENTIC_GROUP_1_ID/AGENTIC_GROUP_2_ID) |
Agentic group tests, with the agents in GROUP_AGENT_1_UID/GROUP_AGENT_2_UID |
✅ Yes |
Reserved for generated data — tests create their own throwaway fixtures with these prefixes and delete them afterwards; npm run e2e:cleanup sweeps any a failed run leaves behind. Don’t create your own users or groups with them:
groups e2e-group-tmp-* (guid) and E2E_Test_* (name), users e2e-user-tmp-* and e2e-user-journey-* (uid).
Engineering & Testing groups — create two public groups named exactly Engineering and exactly Testing (any guids). Add e2e-user-1 to Engineering (the tests send it a message as e2e-user-1 to bring it into the list, then pin it) and e2e-user-2 to Testing (used to send an incoming). The suite resolves both by name at runtime, so no guids go in env. Treat Testing as a free secondary group for future tests.
Pin & Save prerequisites
The pin/save suites (e2e/pin-messages, e2e/save-messages, and the “Pin conversation” block in e2e/conversations) need these on the E2E app:
- Enable in the dashboard:
features.ux.messages.pinned.enabled, features.ux.messages.saved.enabled, features.ux.conversations.pinned.enabled.
- Pin-message limit: set
features.ux.messages.pinned.limit to 5 and E2E_PIN_MESSAGES_LIMIT=5 — the limit test only runs at that cap.
- Strategy roles:
e2e-user-1 is owner/admin; e2e-user-2 is a participant. The UI Kit shows Pin/Unpin to every member and the server enforces who may act.
- Participant permissions: keep the default scope permissions for the participant role — pin denied, unpin denied, pinned-messages listing allowed. The permission tests exercise those denials live against the server. A denied listing can’t coexist with them, so those tests simulate the server’s permission error for the pinned-list request instead — no extra dashboard setup or env flags.
- Each test clears its own pinned/saved state over REST first, so the low pin/save caps never leak between tests. Conversation-pin tests system-pin Strategy and pin only the Engineering chat (Bob stays a read-only fixture).
Moderation prerequisites
e2e/message-actions/moderation.spec.ts reports a message and checks that the profanity filter blocks one. Both need the Moderation feature on the E2E app, with profanity filtering turned on; without them those two tests skip with the reason. They act only on throwaway users and groups.
Thread subscription prerequisites
e2e/thread-subscription needs no dashboard flag of its own, but:
- Stickers (with a sticker pack) and Polls must be enabled (step 2) — the “auto-subscribe by message type” tests send one of each.
- Presigned URLs must be on (step 2) — one test sends an image.
- Runs against Strategy (group cases) and the Bob Smith 1:1 — thread subscription is offered in 1:1 as well as groups, so the 1:1 case asserts the option is present.
Optional fixtures — multi-attachment error states
Two tests in e2e/multi-attachment/multi-attachment.spec.ts exercise the composer’s
rejected (non-retryable) upload states. They need inputs that are impractical to
commit (a huge file) or that depend on dashboard config, so they skip themselves
unless you add a matching fixture to e2e/fixtures/. The lookup is by name prefix,
so the extension is up to you (within the limits noted below).
1. File size exceeded — e2e-oversize.*
Any single file larger than 100 MB (any extension) in e2e/fixtures/. You can generate one with:
# from sample-app/
head -c 150000000 /dev/urandom > e2e/fixtures/e2e-oversize.txt # ~150 MB
2. File type not supported — e2e-blocked-mime.* + E2E_BLOCKED_MIME_TYPE
This test needs both of the following — if either is missing it is skipped:
- A fixture named
e2e-blocked-mime.* in e2e/fixtures/. Its extension must not
be png, mp4, mp3, or pdf (so it can’t collide with the standard fixtures). The
file’s bytes are what get uploaded; the extension itself doesn’t matter beyond that.
E2E_BLOCKED_MIME_TYPE in .env.e2e, set to the exact MIME type you denied in the
dashboard (e.g. E2E_BLOCKED_MIME_TYPE=image/svg+xml). The test attaches this MIME to
the upload explicitly. This is required because Playwright can’t infer a MIME for exotic
extensions and would send an empty one — the server then rejects with
mimeType is required (a retryable failure) instead of the permission-denied
rejected state the test asserts. There is no fallback: the MIME must come from this
env var and must match what you denied.
Where to set the restriction: on the Strategy group → Scope permissions → Admin
role. The E2E suite runs against the Strategy group and the e2e user e2e-user-1 is normally an
admin/owner there, so blocking the MIME type for the Admin scope reliably applies to the
uploads under test.
Quick Start
npm ci # repo root
cd sample-app && npm ci
cp .env.e2e.example .env.e2e # fill in credentials
npx playwright install chromium # once
npm run e2e:seed # seed test data
UIKIT_LOCAL=1 npm run e2e # run against your local UI Kit source
Help and Support
For issues running the project or integrating with our UI Kits, consult our documentation or create a support ticket or seek real-time support via the CometChat Dashboard.
评论