Skip to navigation
ReferenceMKPlayer customization

UI configuration and variants

uiConfig controls global playback UI behavior and can be shared across custom and responsive UI variants.

uiConfig example

const uiConfig = {
  disableAutoHideWhenHovered: false,
  container: HTMLElement,
  disableStorageApi: false,
  autoUiVariantResolve: false,
  playbackSpeedSelectionEnabled: true,
  metadata: {
    markers: [
      { time: 24, title: "Marker1" },
      { time: 69, title: "Marker2" },
    ],
  },
};

Key fields from the source guide:

disableAutoHideWhenHovered: keeps the control bar visible while the cursor is over the player.

  • playbackSpeedSelectionEnabled: enables playback speed controls in settings.

  • metadata.markers: adds visual seekbar markers at specific timestamps.

Build a custom browser UI with customUi

const simpleUI = new mkplayercustomuiPlugin.MKCustomizeUI.UIContainer({
  components: [
    new mkplayercustomuiPlugin.MKCustomizeUI.SubtitleOverlay(),
    settingsPanel, // Contains selection controls on the settings panel
    new mkplayercustomuiPlugin.MKCustomizeUI.BufferingOverlay(),
    new mkplayercustomuiPlugin.MKCustomizeUI.ReplayButton(),
    new mkplayercustomuiPlugin.MKCustomizeUI.PlaybackToggleButton(),
    new mkplayercustomuiPlugin.MKCustomizeUI.QuickSeekButton({ seekSeconds: -10 }),
    new mkplayercustomuiPlugin.MKCustomizeUI.QuickSeekButton({ seekSeconds: 10 }),
    new mkplayercustomuiPlugin.MKCustomizeUI.VolumeToggleButton(),
  ],
});
uiManager = mkCustomizeUI.customUi(simpleUI, uiConfig);

This pattern creates a custom UI container and attaches it through customUi.

The source guide’s browser custom UI example includes:

  • Subtitles and overlays (subtitle display, buffering indicator, play/pause overlay, error messages)

  • Settings panel options for video quality, audio quality, audio track, playback speed, and subtitles

  • Control bar items such as replay, play/pause, skip -10s/+10s, volume, PiP, fullscreen, and settings

  • Title bar metadata display

Build responsive UIs with customUiVariant

const isSmallScreen = (context) => {
  return context.documentWidth < 800;
};
function createMobileUIContainer() {
  return mkCustomizeUI.modernSmallScreenUI();
}
const simpleUI = createBrowserUIContainer();
uiManager = mkCustomizeUI.customUiVariant(
  [
    {
      ui: createMobileUIContainer(),
      condition: isSmallScreen,
    },
    {
      ui: simpleUI,
    },
  ],
  uiConfig
);

Behavior:

  • Mobile variant is selected when isSmallScreen returns true.

  • Desktop/browser UI is used as fallback when no condition matches.

  • A shared uiConfig applies across all variants.

Lifecycle events

Use lifecycle hooks to observe when variants resolve and become active:

uiManager.onActiveUiChanged.subscribe(() => {
  console.log("[customUi] UI is ready, attaching onUiVariantResolve");
});
uiManager.onUiVariantResolve.subscribe((context) => {
  console.log("[customUi] onUiVariantResolve fired:", context);
});

  • onActiveUiChanged: triggered when the active UI is fully attached.

  • onUiVariantResolve: triggered when the variant-selection logic runs.

UI factory variant shortcuts

The guide also includes built-in factory-based options:

uiManager = mkCustomizeUI.buildDefaultUI(uiConfig);
uiManager = mkCustomizeUI.buildDefaultSmallScreenUI(uiConfig);
uiManager = mkCustomizeUI.buildModernTvUI(uiConfig);

  • buildDefaultUI: default responsive UI that adapts between browser and mobile dimensions:

  • buildDefaultSmallScreenUI: default small-screen style UI layout:

  • buildModernTvUI: modern TV playback UI layout: