Call Layouts

Customize CometChat Calls SDK v5 call layouts on iOS with tile, spotlight, sidebar views, layout changes, and layout events.

Choose how participants are displayed during a call. The SDK provides multiple layout options to suit different use cases like team meetings, presentations, or one-on-one calls.

Available Layouts

Layout	Description	Best For
.tile	Grid layout with equally-sized tiles for all participants	Team meetings, group discussions
.spotlight	Large view for the other participant, small tile for yourself	One-on-one calls, presentations, webinars
.sidebar	Main speaker with participants in a sidebar	Interviews, panel discussions

Set Initial Layout

Configure the layout when joining a session using SessionSettingsBuilder:

Swift

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setLayout(.tile)
    .build()

CometChatCalls.joinSession(
    sessionID: sessionId,
    callSetting: sessionSettings,
    container: callViewContainer,
    onSuccess: { message in
        print("Joined with TILE layout")
    },
    onError: { error in
        print("Failed: \(error?.errorDescription ?? "")")
    }
)

Objective-C

SessionSettings *sessionSettings = [[[CometChatCalls sessionSettingsBuilder]
    setLayout:LayoutTypeTile]
    build];

[CometChatCalls joinSessionWithSessionID:sessionId
                             callSetting:sessionSettings
                               container:self.callViewContainer
                               onSuccess:^(NSString * message) {
    NSLog(@"Joined with TILE layout");
} onError:^(CometChatCallException * error) {
    NSLog(@"Failed: %@", error.errorDescription);
}];

Change Layout During Call

Switch layouts dynamically during an active call using setLayout():

Swift

// Switch to Spotlight layout
CallSession.shared.setLayout("SPOTLIGHT")

// Switch to Tile layout
CallSession.shared.setLayout("TILE")

// Switch to Sidebar layout
CallSession.shared.setLayout("SIDEBAR")

Objective-C

// Switch to Spotlight layout
[[CallSession shared] setLayout:@"SPOTLIGHT"];

// Switch to Tile layout
[[CallSession shared] setLayout:@"TILE"];

// Switch to Sidebar layout
[[CallSession shared] setLayout:@"SIDEBAR"];

Each participant can choose their own layout independently. Changing your layout does not affect other participants.

Listen for Layout Changes

Monitor layout changes using LayoutListener:

Swift

class CallViewController: UIViewController, LayoutListener {
    
    override func viewDidLoad() {
        super.viewDidLoad()
        CallSession.shared.addLayoutListener(self)
    }
    
    deinit {
        CallSession.shared.removeLayoutListener(self)
    }
    
    func onCallLayoutChanged(layoutType: LayoutType) {
        switch layoutType {
        case .tile:
            print("Switched to Tile layout")
        case .spotlight:
            print("Switched to Spotlight layout")
        case .sidebar:
            print("Switched to Sidebar layout")
        default:
            break
        }
        // Update layout toggle button icon
        updateLayoutIcon(layoutType)
    }

    func onParticipantListVisible() {}
    func onParticipantListHidden() {}
    func onPictureInPictureLayoutEnabled() {}
    func onPictureInPictureLayoutDisabled() {}
}

Objective-C

@interface CallViewController () <LayoutListener>
@end

@implementation CallViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    [[CallSession shared] addLayoutListener:self];
}

- (void)dealloc {
    [[CallSession shared] removeLayoutListener:self];
}

- (void)onCallLayoutChangedWithLayoutType:(LayoutType)layoutType {
    // Update layout toggle button icon
    [self updateLayoutIcon:layoutType];
}

- (void)onParticipantListVisible {}
- (void)onParticipantListHidden {}
- (void)onPictureInPictureLayoutEnabled {}
- (void)onPictureInPictureLayoutDisabled {}

@end

Hide Layout Toggle Button

To prevent users from changing the layout, hide the layout toggle button in the call UI:

Swift

let sessionSettings = CometChatCalls.sessionSettingsBuilder
    .setLayout(.spotlight)           // Fixed layout
    .hideChangeLayoutButton(true)    // Hide toggle button
    .build()

Objective-C

SessionSettings *sessionSettings = [[[[CometChatCalls sessionSettingsBuilder]
    setLayout:LayoutTypeSpotlight]
    hideChangeLayoutButton:YES]
    build];