> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-feature-react-native-sdk-quotedmessage-a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started With CometChat React UI Kit in Astro

The CometChat platform lets you add in‑app chat with minimal effort. In Astro, you can integrate CometChat in two primary ways:

* Using the CometChat JavaScript SDK directly for framework-agnostic control
* Using the CometChat React UI Kit via the `@astrojs/react` integration to get prebuilt, themeable chat UI

This guide shows you CometChat React UI Kit Integration so you can quickly enable one-to-one and group messaging in your Astro app.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/HFXOvmhiLRb5ClID/images/94312eb7-intro_web_screens-7ee27b256c54ea069273e198ec2aad4e.png?fit=max&auto=format&n=HFXOvmhiLRb5ClID&q=85&s=21d2b906314a417cb1a0d583c64ef822" alt="CometChat prebuilt chat UI screens overview" />
</Frame>

***

***

## Prerequisites

Before installing the CometChat SDK or UI Kit, create a CometChat application in the [CometChat Dashboard](https://app.cometchat.com/). The dashboard provides core services including:

* User Management
* Group Chat & Messaging
* Voice & Video Calling
* Real-time Notifications

> To initialize CometChat you need the following from your application:
>
> 1. App ID
> 2. Auth Key
> 3. Region
>
> Keep these ready for the configuration steps below.

***

## Register & Set Up CometChat

Follow these steps to register and prepare your environment.

### Step 1: Register on CometChat

Sign up or log in to the CometChat Dashboard.

🔗 **[Sign in to CometChat](https://app.cometchat.com/login)**

### Step 2: Get Your Application Keys

Create a new app and copy your credentials:

1. Go to your App → Credentials
2. Note the App ID, Auth Key, and Region

<Info>
  Each CometChat application can power a single client app. Users in the same app can chat across platforms (web and mobile).
</Info>

### Step 3: Set Up Your Development Environment

Make sure your system meets these requirements:

* Node.js installed
* A code editor like [Visual Studio Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/)
* npm, pnpm, or Yarn

***

## Built With

The Astro integration relies on the following technologies:

| Technology                                                                     | Description                                                  |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| [Node.js](https://nodejs.org/)                                                 | JavaScript runtime environment                               |
| [npm](https://www.npmjs.com/)                                                  | Package manager                                              |
| [Astro](https://astro.build/)                                                  | Web framework for content-focused sites                      |
| [@astrojs/react](https://docs.astro.build/en/guides/integrations-guide/react/) | Optional: React integration for using CometChat React UI Kit |

***

## Getting Started

### Step 1: Create an Astro Project

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm create astro@latest
    cd <my-astro-app>
    npm install
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm create astro@latest my-astro-app --template basics
    cd <my-astro-app>
    pnpm install
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn create astro my-astro-app --template basics
    cd <my-astro-app>
    yarn
    ```
  </Tab>
</Tabs>

<Tip>
  Prefer SSR or hybrid rendering? Astro supports islands and client hydration. CometChat’s UI and SDK must run on the client.
</Tip>

***

### Step 2: Install Dependencies

Choose one of the following:

* JavaScript SDK only (maximum control)
* React UI Kit (prebuilt UI) with Astro’s React integration

<Tabs>
  <Tab title="Install CometChat UI Kit">
    ```bash theme={null}
    npm i @cometchat/chat-uikit-react
    ```
  </Tab>

  <Tab title="Add React to Astro">
    ```bash theme={null}
    npx astro add react
    ```

    After installing, ensure the React integration exists in `astro.config.mjs`:

    ```js theme={null}
    import { defineConfig } from 'astro/config'
    import react from '@astrojs/react'

    export default defineConfig({
      integrations: [react()],
    })
    ```
  </Tab>
</Tabs>

<Info>
  Create a `.env` file at the project root and add the following environment variables used by the examples:

  ```bash theme={null}
  PUBLIC_COMETCHAT_APP_ID=your_app_id
  PUBLIC_COMETCHAT_REGION=your_region
  PUBLIC_COMETCHAT_AUTH_KEY=your_auth_key
  # For one-to-one and tab-based examples
  PUBLIC_COMETCHAT_LOGIN_UID=cometchat-uid-3
  PUBLIC_COMETCHAT_TARGET_UID=cometchat-uid-1
  ```
</Info>

***

### Step 3: Initialize CometChat (UI Kit)

Use a shared initializer that reads from environment variables and initializes the React UI Kit. This pattern matches the example projects.

```js theme={null}
// src/lib/cometchat-init.js
import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-react";

const APP_ID   = import.meta.env.PUBLIC_COMETCHAT_APP_ID;
const REGION   = import.meta.env.PUBLIC_COMETCHAT_REGION;
const AUTH_KEY = import.meta.env.PUBLIC_COMETCHAT_AUTH_KEY;

export async function initCometChat() {
  if (!APP_ID || !REGION || !AUTH_KEY) {
    throw new Error("Missing PUBLIC_COMETCHAT_* env vars.");
  }

  const settings = new UIKitSettingsBuilder()
    .setAppId(APP_ID)
    .setRegion(REGION)
    .setAuthKey(AUTH_KEY) // use Auth Tokens in prod
    .subscribePresenceForAllUsers()
    .build();

  await CometChatUIKit.init(settings);
}

export async function ensureLogin(uid) {
  const existing = await CometChatUIKit.getLoggedinUser();
  if (existing && existing.getUid() !== uid) {
    await CometChatUIKit.logout();
  }
  const current = await CometChatUIKit.getLoggedinUser();
  if (!current) {
    await CometChatUIKit.login(uid);
  }
}
```

<Info>
  Replace placeholders with your actual CometChat credentials before testing.
</Info>

***

### Step 4: User Login

The example islands handle login automatically using `ensureLogin(uid)` from `src/lib/cometchat-init.js`. Configure `PUBLIC_COMETCHAT_LOGIN_UID` (and `PUBLIC_COMETCHAT_TARGET_UID` for one-to-one) in your `.env`.

<Note>
  <strong>Security Best Practices</strong>

  * Auth Key is suitable for POCs and early testing.
  * In production, prefer an <a href="/ui-kit/react/methods#login-using-auth-token">Auth Token</a> issued by your backend.
</Note>

<Info>
  Test UIDs you can use immediately: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4`, `cometchat-uid-5`.
</Info>

***

### **Step 5: Choose a Chat Experience**

Integrate a conversation view that suits your application's **UX requirements**. Below are the available options:

***

#### **1️⃣ Conversation List + Message View**

**Best for:** Applications that need a **two-panel layout**, such as web-based chat interfaces (e.g., WhatsApp Web, Slack).

**Features:**

* **Two-panel layout** – Displays the conversation list on the left and the active chat window on the right.
* **One-to-one & group conversations** – Seamless switching between private and group chats.
* **Multiple conversations** – Effortlessly switch between different chat windows.
* **Easy navigation** – Intuitive UI for finding and accessing chats quickly.
* **Tap-to-view on mobile** – In mobile layouts, tapping a conversation opens the **Message View**, optimizing space.
* **Real-time updates** – Auto-refreshes messages and conversation lists.
* **Message sync** – Ensures messages stay updated across all sessions and devices.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/-YC7tOebleeoFejE/images/e6411d13-chat_experience_sidebar_message-35c431d8bf694e5690e4e0f3a74165af.png?fit=max&auto=format&n=-YC7tOebleeoFejE&q=85&s=03a9df5c80f787357ebc4508839a88cb" width="1282" height="802" data-path="images/e6411d13-chat_experience_sidebar_message-35c431d8bf694e5690e4e0f3a74165af.png" />
</Frame>

**Recommended for:**

* Desktop-first applications
* Apps requiring a **rich user experience** with seamless navigation
* Platforms supporting both **individual and group messaging**
* **Mobile-friendly** apps needing a **tap-to-open message view**

[Integrate Conversation List + Message](./astro-conversation)

***

#### **2️⃣ One-to-One/Group Chat**

**Best for:** Apps that require a **focused, direct messaging experience** without a sidebar.

**Features:**

* **Dedicated chat window** – Ideal for one-on-one or group messaging.
* **No conversation list** – Users directly enter the chat without navigating through a list.
* **Supports both One-to-One and Group Chats** – Easily configurable with minor code modifications.
* **Optimized for mobile** – Full-screen chat experience without distractions.
* **Seamless real-time communication** – Auto-updates messages for a smooth experience.
* **Ideal for support chat or community-based messaging.**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/sVDw7GNAn28WGWte/images/4d640baf-chat_experience_one_on_one-db9d6d7716241c59bb026625b05019fe.png?fit=max&auto=format&n=sVDw7GNAn28WGWte&q=85&s=06320cc3e46aa95cb0538c84df500aae" width="1282" height="802" data-path="images/4d640baf-chat_experience_one_on_one-db9d6d7716241c59bb026625b05019fe.png" />
</Frame>

**Recommended for:**

* **Support chat applications** – Direct user-agent communication.
* **Apps focusing on direct messaging** – No distractions from other conversations.
* **Community or group chat applications** – A structured way to interact in groups.
* **Mobile-first applications** – Designed for compact and dedicated messaging experiences.

[Integrate One-to-One/Group Chat](./astro-one-to-one-chat)

***

#### **3️⃣ Tab-Based Chat Experience**

**Best for:** Apps that need a **structured, multi-feature navigation system** for seamless interaction between **chats, calls, users, and settings**.

**Features:**

* **Tab Navigation** – Easily switch between **Chat, Call Logs, Users, and Settings**.
* **Dedicated Chat Window** – Full-screen messaging experience for focused communication.
* **No Sidebar** – Unlike multi-panel UI, this design prioritizes individual interactions.
* **Unified Experience** – Users can seamlessly manage conversations, call history, and settings from a single interface.
* **Scalable for future features** – Easily extend to include more functionalities such as notifications or contact management.
* **Optimized for both desktop and mobile** – Ensures a smooth experience across different screen sizes.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/8YlylzCf9CehSaWO/images/ca9f09bf-chat_experience_full_tab_based-9900ef578ec8687610d21535089554b2.png?fit=max&auto=format&n=8YlylzCf9CehSaWO&q=85&s=778d316df1879c4e649ae650a231b095" width="1282" height="802" data-path="images/ca9f09bf-chat_experience_full_tab_based-9900ef578ec8687610d21535089554b2.png" />
</Frame>

**Recommended for:**

* **Apps requiring structured navigation** – Clearly separate chat, calls, and settings.
* **Multi-feature chat apps** – Supporting different functionalities in an organized way.
* **Mobile-first applications** – Ideal for apps needing tab-based UI for easy access to features.
* **Support & enterprise chat solutions** – Perfect for help desks, business chat platforms, and customer support apps.

[Integrate Tab-Based Chat](./astro-tab-based-chat)

***

## Build Your Own Chat Experience

If you need full control, combine the JavaScript SDK with your own UI or mix Astro islands with select UI Kit components. Customize themes, behaviors, and data flows as needed.

**Key Areas to Explore:**

* [React Sample App](https://github.com/cometchat/cometchat-uikit-react/tree/v6/sample-app)
* [Core Features](./core-features)
* [Components](./components-overview)
* [Themes](./theme)
* [Build Your Own UI](./../../../sdk/javascript/overview)

***

## Next Steps

Proceed with your chosen experience:

* Conversation + Messages (UI Kit) in Astro using `CometChatConversationsWithMessages`
* One-to-One/Group Messages (UI Kit) in Astro using `CometChatMessages`
* Tab-Based Chat (UI Kit) in Astro using `CometChatFullScreenView`
* Advanced customizations with themes and components

<Check>
  You’ve set up CometChat in your Astro app. Initialize, log in, and render your preferred chat experience.
</Check>