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

# New Chat / Create Conversation in Your Flutter Chat App

Enable users to start one-on-one or group chats by integrating CometChat’s avatar menu and `CometChatContacts` screen, providing a seamless flow from the dashboard to a conversation.

## Overview

* Users can start a new one-on-one or group chat by tapping the avatar in the top bar, selecting “Create Conversation,” and choosing a contact from a searchable list.
* Streamlines finding contacts or groups and initiating conversations, improving user experience and engagement.
* Quick creation or opening of chats directly from the main screen.

## Prerequisites

* Flutter project with **CometChat UIKit Flutter v5** installed
* CometChat credentials (`appID`, `region`, `authKey`) initialized
* Navigation configured in your app
* Internet/network permissions granted

## 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          |
| `CometChatContactsController`        | Manages tab switching and item selection        |
| `CometChatUsers` / `CometChatGroups` | Lists users or groups with search and selection |
| `PageManager`                        | Handles navigation to the chat screen           |

## Integration Steps

### Add Avatar Menu

Show the avatar in the app bar and open a menu on tap.

```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') openCreateConversation(context);
  },
);
```

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

### Open Start Conversation Screen

Navigate to the “Start Conversation” screen when “Create Conversation” is selected.

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

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

### Select User or Group

Let the user pick a contact or group to chat with.

```dart theme={null}
CometChatContactsController(
  currentView: [
    CometChatUsers(
      hideAppbar: true,
      onItemTap: (context, user) => _onItemTap(context: context, user: user),
    ),
    CometChatGroups(
      hideAppbar: true,
      onItemTap: (context, group) => _onItemTap(context: context, group: group),
    ),
  ],
);
```

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

### Navigate to Chat

Open the chat screen for the selected user or group.

```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);
  }
}
```

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

## Implementation Flow

1. User taps avatar → menu opens
2. User selects “Create Conversation” → navigates to `CometChatContacts`
3. User searches and selects a user or group → triggers `_onItemTap`
4. App navigates to the chat screen for the selected user or group

## Customization Options

* **Styling:** Customize avatar, menu, and contact list appearance via UIKit theming
* **APIs:** Use callbacks like `onSearch` and `onItemTap` for custom logic
* **Configuration:** Adjust tab visibility, search placeholder, or add custom menu actions

## Filtering / Edge Cases

* **Filtering:** `CometChatUsers` and `CometChatGroups` provide real-time search
* **Empty Results:** Display an empty state if no matches are found
* **Blocked Users:** Exclude blocked users from search and messaging

## Error Handling & Blocked-User Handling

* **UI States:** Default UIKit states handle network errors or empty results
* **Feedback:** Use `SnackBar` or `Toast` for custom error messages
* **Blocked Users:** Blocked users cannot be selected or messaged

## Optional Context-Specific Notes

* **User vs. Group:** The flow is identical; only the data source changes

## Summary / Feature Matrix

| Feature              | Component / Method                   | File(s)                                                                                                                                                         |
| -------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Show avatar/menu     | `PopupMenuButton`, `CometChatAvatar` | [`dashboard.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)                                                  |
| Open conversation UI | `CometChatContacts`                  | [`dashboard.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/dashboard.dart)                                                  |
| List/search users    | `CometChatUsers`                     | [`cometchat_contacts_controller.dart`](https://github.com/cometchat/cometchat-uikit-flutter/blob/v5/sample_app/lib/contacts/cometchat_contacts_controller.dart) |
| List/search 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 & Further Reading

<CardGroup>
  <Card title="Flutter Sample App">
    Fully functional sample applications to accelerate your development.

    [View on GitHub](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/sample_app)
  </Card>

  <Card title="UI Kit Source Code">
    Access the complete UI Kit source code on GitHub.

    [View on GitHub](https://github.com/cometchat/cometchat-uikit-flutter/tree/v5/chat_uikit)
  </Card>
</CardGroup>