Skip to main content

Custom Component Replacement

Use this path when targeted overrides are not enough and you need to replace larger UI blocks or entire presentation surfaces with your own components.

When this is the right choice​

  • Your product has a strong existing design system.
  • You need to replace compound components rather than individual controls.
  • You still want MediaSFU workflow and state behavior, but not the stock UI composition.

What customComponent buys you​

customComponent is the bridge between the prebuilt packages and a fully bespoke workspace. Instead of only swapping cards or modal surfaces, you receive live MediaSFU helpers and can render your own dashboard, CRM panel, operator console, or branded meeting shell while the SDK continues to manage sockets, transports, and core workflow state.

Where parameters comes from​

In a custom workspace, the parameters prop is the same live helper bundle that headless mode exposes through sourceParameters and updateSourceParameters. It carries room state, participant lists, modal visibility updaters, and action helpers such as clickVideo, clickAudio, clickScreenShare, and launchRecording.

That means the inline button bars in starter tutorials are intentionally minimal. They prove the workflow first. Once the flow is stable, prefer shipped MediaSFU surfaces when they already exist. For example, use RecordingModal or ModernRecordingModal, or override uiOverrides.recordingModal, instead of rebuilding recording UX from scratch.

Read Media lifecycle for the helper-bundle mental model and UI overrides for component-level replacement strategy.

By framework​

FrameworkHookBest forCaveat
ReactJScustomComponent={CustomWorkspace}Fully custom web workspaces with the richest reference behaviorUse this as the reference for other framework custom shells.
Angular[customComponent]="customWorkspace"Angular-first apps that want custom templates around MediaSFU logicKeep Angular shell concerns separate from MediaSFU runtime helpers.
React NativecustomComponent={CustomWorkspace}Mobile-native host or participant workspacesValidate on device after replacing interaction-heavy surfaces.
React Native ExpocustomComponent={CustomWorkspace}Expo-managed custom shells and playbook-driven explorationPhysical-device checks still matter for media and permission flows.
VuecustomComponent={CustomWorkspace}Branded Vue shells with composition-friendly state flowPair with uiOverrides if only some surfaces need replacing.

In every UI SDK, customComponent works best when you already understand the prebuilt flow and know which helpers your replacement surface needs.

Working method​

  1. Validate the stock flow first.
  2. Decide whether you need customComponent alone, or returnUI={false} plus a fully bespoke shell.
  3. Replace one surface at a time, keeping socket/state behavior unchanged.
  4. Re-test the affected room flows after each major replacement.
  1. Start with UI overrides to understand the SDK's surface area.
  2. Move to customComponent once you know the stock shell is the limiting factor.
  3. Keep the runtime contract fixed while changing layout and user interaction flow.
  4. Use the framework SDK docs to study the existing custom workspace examples before building your own.