Call Layouts

Customize CometChat Calls SDK v5 call layouts on Flutter 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:

SessionSettings sessionSettings = SessionSettingsBuilder()
    .setLayout(LayoutType.tile)
    .build();

CometChatCalls.joinSession(
  sessionId: sessionId,
  sessionSettings: sessionSettings,
  onSuccess: (Widget? callWidget) {
    debugPrint("Joined with TILE layout");
    // Place callWidget in your widget tree
  },
  onError: (CometChatCallsException e) {
    debugPrint("Failed: ${e.message}");
  },
);

Change Layout During Call

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

CallSession? callSession = CallSession.getInstance();

// Switch to Spotlight layout
await callSession?.setLayout(LayoutType.spotlight);

// Switch to Tile layout
await callSession?.setLayout(LayoutType.tile);

// Switch to Sidebar layout
await callSession?.setLayout(LayoutType.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 LayoutListeners:

class _LayoutListener extends LayoutListeners {
  @override
  void onCallLayoutChanged(LayoutType layoutType) {
    switch (layoutType) {
      case LayoutType.tile:
        debugPrint("Switched to Tile layout");
        break;
      case LayoutType.spotlight:
        debugPrint("Switched to Spotlight layout");
        break;
      case LayoutType.sidebar:
        debugPrint("Switched to Sidebar layout");
        break;
    }
    // Update layout toggle button icon
    updateLayoutIcon(layoutType);
  }
  // every other callback already defaults to a no-op on the abstract class —
  // override only what you need (onParticipantListVisible, onParticipantListHidden, onPictureInPictureLayoutEnabled, onPictureInPictureLayoutDisabled).
}

CallSession? callSession = CallSession.getInstance();

callSession?.layoutListener = _LayoutListener();

Flutter listeners are not lifecycle-aware. You must manually remove the layout listener in your widget’s dispose() method to prevent memory leaks:

CallSession.getInstance()?.layoutListener = null;

Hide Layout Toggle Button

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

SessionSettings sessionSettings = SessionSettingsBuilder()
    .setLayout(LayoutType.spotlight) // Fixed layout
    .hideChangeLayoutButton(true)    // Hide toggle button
    .build();