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

# Create Conversation

> Create new one-to-one or group conversations in CometChat iOS UI Kit with user and group discovery, search, tabs, and navigation.

Enable users to start new 1:1 or group chats in your iOS app using CometChat's UIKit for iOS by integrating the `CreateConversationVC` screen.

## Overview

The `CreateConversation` component enables users to:

* Browse CometChat users and groups via native list components
* Search within users and groups
* Toggle between "Users" and "Groups" tabs using a segmented control
* Swipe between lists with a `UIPageViewController`
* Navigate to `MessagesVC` upon selecting a user or group

## Prerequisites

Before implementing this feature, ensure you have:

* Completed [Getting Started](/ui-kit/ios/getting-started) setup
* CometChat UIKit v5+ installed via CocoaPods or Swift Package Manager
* User authenticated with `CometChatUIKit.login()` before presenting this screen
* A `UINavigationController` embedded in your flow
* `MessagesVC` implemented to handle chat screens

## Components

| Component              | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `UISegmentedControl`   | Switches between "Users" and "Groups" tabs         |
| `UIPageViewController` | Enables swipe navigation between list views        |
| `CometChatUsers`       | Displays the list of CometChat users               |
| `CometChatGroups`      | Displays the list of CometChat groups              |
| `MessagesVC`           | Chat interface, launched upon item selection       |
| `searchController`     | Provides search for both users and groups          |
| `CometChatTheme`       | Applies theming (colors, fonts) for UI consistency |
| `CometChatTypography`  | Defines text styles for segment labels             |

## Integration Steps

### Step 1: Present the Create Conversation Screen

Push `CreateConversations` to allow starting a chat:

```swift lines theme={null}
import UIKit
import CometChatSDK

class HomeViewController: UIViewController {
    
    func showCreateConversation() {
        // Initialize the create conversation view controller
        let createVC = CreateConversationVC()
        
        // Push onto navigation stack
        navigationController?.pushViewController(createVC, animated: true)
    }
}
```

This provides the entry point to the create-conversation flow.

**File reference:** [`HomeScreenViewController.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/HomeScreenViewController.swift)

### Step 2: Set Up the User Interface

Build the segmented control and page view controller:

```swift lines theme={null}
import UIKit
import CometChatUIKitSwift

class CreateConversationVC: UIViewController {
    
    private var segmentedControl: UISegmentedControl!
    private var pageViewController: UIPageViewController!
    private var usersViewController: CometChatUsers!
    private var groupsViewController: CometChatGroups!
    
    override public func viewDidLoad() {
        super.viewDidLoad()
        
        // Set up segmented control, page view controller, and search
        buildUI()
        setupPageViewController()
        
        // Add target for segment changes
        segmentedControl.addTarget(
            self,
            action: #selector(segmentChanged(_:)),
            for: .valueChanged
        )
        
        // Set initial search controller
        navigationItem.searchController = usersViewController.searchController
    }
    
    private func buildUI() {
        // Configure segmented control and page view
    }
    
    private func setupPageViewController() {
        // Initialize page view controller with users and groups
    }
}
```

This initializes the UI elements and search integration.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 3: Configure Segmented Control Navigation

Toggle between user and group lists when the segment changes:

```swift lines theme={null}
@objc public func segmentChanged(_ sender: UISegmentedControl) {
    let index = sender.selectedSegmentIndex
    
    // Determine navigation direction
    let direction: UIPageViewController.NavigationDirection = index == 0 ? .reverse : .forward
    
    // Update search controller based on selected tab
    navigationItem.searchController = (index == 0)
        ? usersViewController.searchController
        : groupsViewController.searchController
    
    // Navigate to the selected page
    pageViewController.setViewControllers(
        [pages[index]],
        direction: direction,
        animated: true
    )
}
```

This keeps the proper search bar and view in sync with the selected tab.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 4: Handle Item Selection

Navigate to `MessagesVC` when a user or group is tapped:

```swift lines theme={null}
// Users list with tap handler
public lazy var usersViewController: CometChatUsers = {
    let vc = CometChatUsers()
    
    // Handle user selection
    vc.set(onItemClick: { [weak self] user, _ in
        let chatVC = MessagesVC()
        chatVC.user = user
        self?.navigationController?.pushViewController(chatVC, animated: true)
    })
    
    // Keep navigation bar visible during search
    vc.searchController.hidesNavigationBarDuringPresentation = false
    
    return vc
}()

// Groups list with tap handler
public lazy var groupsViewController: CometChatGroups = {
    let vc = CometChatGroups()
    
    // Handle group selection
    vc.set(onItemClick: { [weak self] group, _ in
        let chatVC = MessagesVC()
        chatVC.group = group
        self?.navigationController?.pushViewController(chatVC, animated: true)
    })
    
    // Keep navigation bar visible during search
    vc.searchController.hidesNavigationBarDuringPresentation = false
    
    return vc
}()
```

This routes the user to the appropriate chat screen.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

### Step 5: Manage Page View Transitions

Implement data source and delegate for smooth swiping:

```swift lines theme={null}
// MARK: - UIPageViewControllerDataSource
extension CreateConversationVC: UIPageViewControllerDataSource {
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        viewControllerBefore vc: UIViewController
    ) -> UIViewController? {
        guard let idx = pages.firstIndex(of: vc), idx > 0 else { return nil }
        return pages[idx - 1]
    }
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        viewControllerAfter vc: UIViewController
    ) -> UIViewController? {
        guard let idx = pages.firstIndex(of: vc), idx < pages.count - 1 else { return nil }
        return pages[idx + 1]
    }
}

// MARK: - UIPageViewControllerDelegate
extension CreateConversationVC: UIPageViewControllerDelegate {
    
    public func pageViewController(
        _ pvc: UIPageViewController,
        didFinishAnimating finished: Bool,
        previousViewControllers: [UIViewController],
        transitionCompleted completed: Bool
    ) {
        // Sync segmented control with current page
        if completed,
           let current = pvc.viewControllers?.first,
           let idx = pages.firstIndex(of: current) {
            segmentedControl.selectedSegmentIndex = idx
        }
    }
}
```

This synchronizes the segmented control with page swipes.

**File reference:** [`CreateConversations.swift`](https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversations.swift)

## Customization Options

### Segment Styling

Use `CometChatTheme` to customize tint and font:

```swift lines theme={null}
segmentedControl.selectedSegmentTintColor = CometChatTheme.palette.primary
segmentedControl.setTitleTextAttributes([
    .font: CometChatTypography.body,
    .foregroundColor: UIColor.white
], for: .selected)
```

### Labels

Localize or rebrand "USERS" / "GROUPS" labels:

```swift lines theme={null}
segmentedControl.setTitle("Contacts", forSegmentAt: 0)
segmentedControl.setTitle("Teams", forSegmentAt: 1)
```

### Search

Adjust `searchController.placeholder` and styling:

```swift lines theme={null}
usersViewController.searchController.searchBar.placeholder = "Search contacts..."
groupsViewController.searchController.searchBar.placeholder = "Search teams..."
```

## Edge Cases

| Scenario         | Handling                                           |
| ---------------- | -------------------------------------------------- |
| Live search      | Built-in in `CometChatUsers` and `CometChatGroups` |
| Empty states     | Components display default "no results" views      |
| Segment disabled | Hide tabs if only one list is relevant             |

## Error Handling

| Error Type          | Solution                                         |
| ------------------- | ------------------------------------------------ |
| Load errors         | Use `setErrorView()` on list components          |
| Navigation failures | Present an alert if push fails                   |
| Blocked users       | Intercept in `onItemClick` to prevent navigation |

## Feature Matrix

| Feature              | Implementation                                |
| -------------------- | --------------------------------------------- |
| Show create screen   | `showCreateConversation()`                    |
| Tabbed lists         | `UISegmentedControl` + `UIPageViewController` |
| Display users        | `CometChatUsers()`                            |
| Display groups       | `CometChatGroups()`                           |
| Search functionality | `searchController`                            |
| Navigate to chat     | `MessagesVC(user:)` / `MessagesVC(group:)`    |

## Related Components

* [Users](/ui-kit/ios/users) - Display user list
* [Groups](/ui-kit/ios/groups) - Display group list
* [Conversations](/ui-kit/ios/conversations) - Display conversation list

## Related Guides

<CardGroup cols={2}>
  <Card title="Users" icon="user" href="/ui-kit/ios/users">
    Display and select users
  </Card>

  <Card title="Groups" icon="users" href="/ui-kit/ios/groups">
    Display and select groups
  </Card>

  <Card title="Conversations" icon="comments" href="/ui-kit/ios/conversations">
    View recent conversations
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Sample App" href="https://github.com/cometchat/cometchat-uikit-ios/tree/v5/SampleApp">
    Explore the complete create-conversation flow
  </Card>

  <Card title="UIKit Source" href="https://github.com/cometchat/cometchat-uikit-ios/blob/v5/SampleApp/View%20Controllers/CometChat%20Components/CreateConversationVC.swift">
    Browse the source for CreateConversationVC
  </Card>
</CardGroup>