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.

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

Open Start Conversation Screen

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

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

File reference:
sample_app/lib/dashboard.dart

Select User or Group

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

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

Navigate to Chat

Open the chat screen for the selected user or group.

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

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
Open conversation UI	CometChatContacts	dashboard.dart
List/search users	CometChatUsers	cometchat_contacts_controller.dart
List/search groups	CometChatGroups	cometchat_contacts_controller.dart
Handle selection	_onItemTap	page_manager.dart
Navigate to chat	PageManager.navigateToMessages	page_manager.dart

Next Steps & Further Reading

Flutter Sample App

Fully functional sample applications to accelerate your development.

View on GitHub

UI Kit Source Code

Access the complete UI Kit source code on GitHub.

View on GitHub