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

# New Chat

> Enable users to start one-on-one or group chats with a searchable contact list in CometChat Flutter UI Kit.

<Accordion title="AI Agent Component Spec">
  | Field          | Value                                                                             |
  | -------------- | --------------------------------------------------------------------------------- |
  | Package        | `cometchat_chat_uikit`                                                            |
  | Key components | `CometChatContacts`, `CometChatUsers`, `CometChatGroups`, `CometChatAvatar`       |
  | Init           | `CometChatUIKit.init(uiKitSettings)` then `CometChatUIKit.login(uid)`             |
  | Entry point    | Avatar menu → "Create Conversation" → `CometChatContacts`                         |
  | Sample app     | [GitHub](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app) |
  | Related        | [All Guides](/ui-kit/flutter/v5/guide-overview)                                   |
</Accordion>

New Chat enables users to start one-on-one or group conversations by selecting from a searchable contact list.

Before starting, complete the [Getting Started](/ui-kit/flutter/v5/getting-started) guide.

***

## Components

| Component / Class             | Role                                             |
| :---------------------------- | :----------------------------------------------- |
| `CometChatAvatar`             | Displays the user avatar in the app bar          |
| `PopupMenuButton`             | Shows menu options when the avatar is tapped     |
| `CometChatContacts`           | UI for the "Start Conversation" screen with tabs |
| `CometChatContactsController` | Manages tab switching and item selection         |
| `CometChatUsers`              | Lists users with search and selection            |
| `CometChatGroups`             | Lists groups with search and selection           |
| `PageManager`                 | Handles navigation to the chat screen            |

***

## Integration Steps

### 1. Add Avatar Menu

Show the avatar in the app bar and open a menu on tap with "Create Conversation" option.

*File: [dashboard.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)*

```dart theme={null}
PopupMenuButton(
  icon: CometChatAvatar(
    width: 40,
    height: 40,
    image: CometChatUIKit.loggedInUser?.avatar,
    name: CometChatUIKit.loggedInUser?.name,
  ),
  itemBuilder: (context) => [
    PopupMenuItem(value: '/Create', child: Text("Create Conversation")),
  ],
  onSelected: (value) {
    if (value == '/Create') {
      Navigator.push(
        context,
        MaterialPageRoute(builder: (context) => CometChatContacts()),
      );
    }
  },
);
```

***

### 2. Open Contacts Screen

Navigate to the `CometChatContacts` screen which provides tabs for Users and Groups.

*File: [dashboard.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)*

```dart theme={null}
void openCreateConversation(BuildContext context) {
  Navigator.push(
    context,
    MaterialPageRoute(builder: (context) => CometChatContacts()),
  );
}
```

***

### 3. Handle User/Group Selection

Wire up the `onItemTap` callback to navigate to the chat screen when a user or group is selected.

*File: [cometchat\_contacts\_controller.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/contacts/cometchat_contacts_controller.dart)*

```dart theme={null}
CometChatUsers(
  hideAppbar: true,
  onItemTap: (context, user) => _onItemTap(context: context, user: user),
);

CometChatGroups(
  hideAppbar: true,
  onItemTap: (context, group) => _onItemTap(context: context, group: group),
);
```

***

### 4. Navigate to Chat

Open the chat screen for the selected user or group using `PageManager`.

*File: [page\_manager.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/utils/page_manager.dart)*

```dart theme={null}
void _onItemTap({required BuildContext context, User? user, Group? group}) {
  if (user != null) {
    PageManager.navigateToMessages(context: context, user: user);
  } else if (group != null) {
    JoinProtectedGroupUtils.onGroupItemTap(context, group);
  }
}
```

***

## Feature Matrix

| Feature          | Component / Method                   | File                                                                                                                                                            |
| :--------------- | :----------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Avatar menu      | `PopupMenuButton`, `CometChatAvatar` | [dashboard.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)                                                    |
| Contacts screen  | `CometChatContacts`                  | [dashboard.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)                                                    |
| List users       | `CometChatUsers`                     | [cometchat\_contacts\_controller.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/contacts/cometchat_contacts_controller.dart) |
| List groups      | `CometChatGroups`                    | [cometchat\_contacts\_controller.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/contacts/cometchat_contacts_controller.dart) |
| Handle selection | `_onItemTap`                         | [page\_manager.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/utils/page_manager.dart)                                       |
| Navigate to chat | `PageManager.navigateToMessages`     | [page\_manager.dart](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/utils/page_manager.dart)                                       |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Users" href="/ui-kit/flutter/v5/users">
    Display and search user lists.
  </Card>

  <Card title="Groups" href="/ui-kit/flutter/v5/groups">
    Display and manage group lists.
  </Card>

  <Card title="Conversations" href="/ui-kit/flutter/v5/conversations">
    View and manage conversation history.
  </Card>

  <Card title="All Guides" href="/ui-kit/flutter/v5/guide-overview">
    Browse all feature and formatter guides.
  </Card>
</CardGroup>