Skip to main content

Headless Mode

Headless mode is the right path when you want MediaSFU workflows, socket/state behavior, and shared business logic without adopting the default UI layout.

When to use headless mode​

  • You want your own app shell and presentation layer.
  • You need the MediaSFU runtime behavior, but not the default UI.
  • You are integrating mediasfu-shared directly or using a framework SDK in a logic-first way.

Headless controls by framework​

FrameworkHeadless switchPre-join bypassHelper handoffBest starting point
ReactJSreturnUI={false}noUIPreJoinOptionsupdateSourceParametersReactJS SDK
Angular[returnUI]="false"[noUIPreJoinOptions]updateSourceParameters outputAngular SDK
React NativereturnUI={false}noUIPreJoinOptionsupdateSourceParametersReact Native SDK
React Native ExporeturnUI={false}noUIPreJoinOptionsupdateSourceParametersExpo SDK
VuereturnUI={false}noUIPreJoinOptionsupdateSourceParametersVue SDK
Sharedn/an/adirect methods, consumers, socketsmediasfu-shared

All UI SDKs now expose the same basic headless pattern: disable default rendering with returnUI={false} or the framework equivalent, provide noUIPreJoinOptions if you want to skip the built-in wizard, then capture live helpers via updateSourceParameters so your custom shell can drive the workflow.

Current best starting points​

Framework notes​

  • ReactJS: the reference behavior is strongest here, so use it to understand the full helper surface before porting a custom shell to another UI SDK.
  • Angular: headless mode is particularly useful when you want to keep Angular routing, DI, and templates while outsourcing MediaSFU runtime logic.
  • React Native / Expo: validate headless flows on a physical device before treating them as closed because permission and media-capture behavior can differ from simulators.
  • Vue: this is a good path when you want composition-friendly state handling while still preserving MediaSFU socket and consumer behavior.
  • Shared: choose this when you are building a wrapper or framework integration rather than adapting a bundled UI package.

Implementation sequence​

  1. Validate a standard join flow first.
  2. Flip returnUI off and wire noUIPreJoinOptions only after the default prebuilt path is known-good.
  3. Capture and store the helper surface from updateSourceParameters before replacing any visible screens.
  4. Validate translation, board sync, screen share, and receive-flow behavior in the target app environment.
  5. Use the package SDK page for the framework-specific examples and prop signatures.