> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mediakind.ferndocs.com/mkio/reference/player-customization/ui-configuration-and-variants/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mediakind.ferndocs.com/_mcp/server.

# UI configuration and variants

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

## uiConfig example

```js
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`

```js
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`

```js
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:

```js
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:

```js
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: