Skip to main content

Choose Your UI Mode

Use this page when you are deciding whether MediaSFU should render the visible room UI or only provide the live runtime behind your app shell.

The short answer​

If you need...Start with
The fastest path with MediaSFU still rendering the visible room experiencereturnUI={true}
Full ownership of the visible product shell from first paintreturnUI={false}
A custom workspace but still within MediaSFU's visible room runtimereturnUI={true} plus customComponent
Mostly stock workflow with selected cards, modals, or menus restyledreturnUI={true} plus uiOverrides

What returnUI actually changes​

returnUI={true}​

MediaSFU mounts a visible UI layer.

  • keep the stock room flow and restyle pieces of it
  • override cards, menus, modals, or helper surfaces
  • replace the main workspace with customComponent while MediaSFU still owns the visible room runtime

returnUI={false}​

MediaSFU runs headless.

  • your app renders the visible shell
  • MediaSFU exposes the live helper bundle through sourceParameters and updateSourceParameters
  • your own components call helpers such as clickAudio, clickVideo, clickScreenShare, and launchRecording

The three common patterns​

1. Override-first​

Use this when the room still looks like MediaSFU, but branded.

<MediasfuGeneric
  connectMediaSFU={true}
  returnUI={true}
  customVideoCard={CompactVideoCard}
  customMiniCard={CompactMiniCard}
  uiOverrides={uiOverrides}
/>

Best fit:

  • compact call products
  • branded cards and control bars
  • teams optimizing for fastest time to demo

2. Custom workspace with MediaSFU still visible​

Use this when the visible product is yours, but MediaSFU can still own the room-shaped runtime around it.

<MediasfuGeneric
  connectMediaSFU={true}
  returnUI={true}
  customComponent={HostDashboard}
/>

Best fit:

  • host dashboards
  • guest queues
  • products that still benefit from MediaSFU's visible runtime contract

3. Full headless shell​

Use this when the visible product must be fully app-owned.

<>
  <MediasfuGeneric
    connectMediaSFU={true}
    returnUI={false}
    sourceParameters={sourceParameters}
    updateSourceParameters={setSourceParameters}
  />
  <OperatorConsole parameters={sourceParameters} />
</>

Best fit:

  • support or CRM consoles
  • non-room workflows
  • products with app-owned navigation, tabs, or shell framing from first paint

How to choose between true and false​

  1. If you want MediaSFU's visible room flow to stay on screen, start with returnUI={true}.
  2. If you only need branding or targeted surface changes, stay with returnUI={true} and use overrides first.
  3. If you need a custom dashboard but can still live inside MediaSFU's visible room runtime, use returnUI={true} plus customComponent.
  4. If your product needs app-owned navigation, sidebars, pane layouts, or a non-room shell from first paint, move to returnUI={false}.
  5. If you expect most user actions to originate from your own workspace instead of MediaSFU surfaces, the headless path is usually cleaner.

How the current starters map to this choice​

StarterDefault angleAlternate angle
Tutorial - WhatsApp-style call screenreturnUI={true} plus light overridesreturnUI={false} plus a compact call shell driven by sourceParameters
Tutorial - Twitch-style host dashboardreturnUI={true} plus customComponentreturnUI={false} plus a headless host dashboard
Tutorial - TikTok Live guest queuereturnUI={true} plus customComponentreturnUI={false} plus a headless queue shell
Tutorial - Support or AI agent consolereturnUI={false} plus a headless consolereturnUI={true} only when the operator workspace can stay room-shaped