Skip to main content

Breakout Rooms in Hybrid and Headless UIs

Breakout rooms are server-side room membership and navigation changes. They are not a filter applied to participant cards. The room engine must confirm membership before the UI selects that room's page and media consumers.

Standard UI​

Use the supplied breakout workspace when possible. Hosts assign participants, select Save, then Start. After editing assignments, save again before updating active rooms. Stop screen sharing before starting groups when the room validation requires it.

Hybrid: preserve Save, Start, and feedback​

ModernBreakoutRoomsModal owns a local plan. Save validates the plan and sets canStartBreakout; Start submits it. Keep the footer visible and render room alerts because returnUI={false} does not mount the SDK's default alert UI.

import type {ComponentProps} from 'react';
import {ModernBreakoutRoomsModal} from 'mediasfu-reactjs';

type BreakoutRoom = ComponentProps<typeof ModernBreakoutRoomsModal>['parameters'];

export function BreakoutPanel({parameters}: {parameters: BreakoutRoom}) {
  const live = parameters.getCurrentParams?.() ?? parameters;
  if (String(live.islevel) !== '2') return null;

  return <section>
    <p>Assign participants, select Save, then Start. Save again after edits.</p>
    {!live.canStartBreakout && <p role="status">Save before Start.</p>}
    {live.alertVisible && <p role="alert">{live.alertMessage}</p>}
    <button onClick={() => live.updateIsBreakoutRoomsModalVisible(true)}>
      Plan breakout rooms
    </button>
    <ModernBreakoutRoomsModal
      isVisible={live.isBreakoutRoomsModalVisible === true}
      onBreakoutRoomsClose={() => live.updateIsBreakoutRoomsModalVisible(false)}
      parameters={live}
      renderMode="inline"
    />
  </section>;
}

Pass the latest room parameters, not the initial seed. Do not infer success from a click or hide validation errors.

Fully custom: submit only a reviewed composition​

setBreakoutRooms starts groups immediately, or updates them when groups are already active; it is not a draft-save function. Your interface must keep a separate draft, validate current participant membership, reject duplicates and empty groups, enforce the room limit, and submit only after explicit review.

import {
  getCurrentParams,
  setBreakoutRooms,
  stopBreakoutRooms,
  type BreakoutParticipantRef,
  type HeadlessParameters,
} from 'mediasfu-reactjs';

export async function submitGroups(
  parameters: HeadlessParameters,
  rooms: BreakoutParticipantRef[][],
) {
  const live = getCurrentParams({parameters});
  if (String(live.islevel) !== '2') {
    return {ok: false, error: 'Only the host can update breakout rooms.'};
  }
  if (!rooms.length || rooms.some((room) => room.length === 0)) {
    return {ok: false, error: 'Every breakout room needs an assignment.'};
  }
  return setBreakoutRooms({parameters: live, rooms});
}

export function returnEveryone(parameters: HeadlessParameters) {
  return stopBreakoutRooms({parameters: getCurrentParams({parameters})});
}

Moving an ordinary participant requires the reassignment workflow. Submit the updated full composition or use the exported assignParticipantToBreakoutRoom({parameters, name, room}) helper. A learner cannot change server membership by clicking a local room tab.

  1. Hosts navigate through the SDK breakout update flow. In React this uses updateHostBreakout with newRoom and prevRoom; -1 is the main room.
  2. Ordinary participants follow their server-assigned memberRoom, not the host's current visit.
  3. After membership confirmation, select the corresponding room page through the SDK pagination path. In React, generatePageContent coordinates page, breakout index, display state, and consumer pause/resume.
  4. A late consumer may arrive after page selection. Reconcile that target page on the matching media update without repeatedly switching an already settled page.
  5. Keep all eligible remote audio renderers mounted. Do not broadly resume all consumers or manually splice the SDK's membership state.

When breakouts end, render the ended/together state, follow the room's return to the main membership, select the main page, and release obsolete breakout renderers. A participant-card filter cannot perform any of those operations.

Test Save-before-Start validation, host visits, a learner with a peer in the same group, late media, reassignment, ended state, return to the main room, reconnect, and final teardown. The Interactive Classroom starter is the recommended product-shaped React reference; other platforms still need their own runtime validation.

Continue with large rooms and moderation, headless UI, and media lifecycle.