> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.