---
title: "Player UI"
slug: "vpe-umd-player-ui"
updated: 2026-09-17T09:22:36Z
published: 2026-09-17T09:22:36Z
canonical: "guide.ncloud-docs.com/vpe-umd-player-ui"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Player UI

Available in Classic and VPC

Player UI explains how to configure options related to the control bar, buttons, progress bar, and other UI elements.

              Note

              

- For descriptions of properties to set options, see the option reference.
- The available options may vary depending on your subscription plan.

## Default option

### Language (multilingual)

Set the language used in the player. If not set, it follows the language used in the browser.

```
const player = new ncplayer("player", {
  lang: "ko", // Language setting ("auto", "ko", "en")
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

## Control bar

### controls (show control bar)

Set whether to display the default control bar UI. If set to `false`, the control bar will not be displayed.

```
const player = new ncplayer("player", {
  controls: true, // Set whether to display the control bar
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

### controlBtn (control bar button UI)

Set whether to show or hide individual buttons in the control bar. Control each button with `true` or `false`.

              Note

              

Available only with the standard plan.

```
const player = new ncplayer("player", {
  controlBtn: {
    play: true,             // Playback button
    progressBar: true,      // Progress bar
    fullscreen: true,       // Full screen button
    volume: true, // Volume button
    times: true,            // Time display
    pictureInPicture: true, // PIP button
    setting: true,          // Settings button
    subtitle: true,         // Subtitle button
  },
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

**controlBtn property**

| Properties | Type | Default value | Description |
| --- | --- | --- | --- |
| play | boolean | true | Play/pause button |
| progressBar | boolean | true | Progress bar |
| fullscreen | boolean | true | Full screen button |
| volume | boolean | true | Volume button |
| times | boolean | true | Display playback time |
| pictureInPicture | boolean | true | PIP (Picture-In-Picture) button |
| setting | boolean | true | Settings button |
| subtitle | boolean | true | Subtitle button |

### progressBarColor (control bar color)

Set the color of the control bar progress bar using a CSS color value.

              Note

              

Available only with the standard plan.

```
const player = new ncplayer("player", {
  progressBarColor: "#2e6ae0", // Specifies the control bar progress color
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

### controlActiveTime (control bar display duration)

Set the time until the control bar automatically hides, in milliseconds (ms). The default value is `3000` (3 seconds).

              Note

              

If set to `controlActiveTime: 0`, the control bar will not be hidden automatically and will always be displayed. This is useful for interfaces where the UI should always be shown, such as live commerce.

```
const player = new ncplayer("player", {
  controlActiveTime: 5000, // Control bar display duration setting (ms)
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

### UI (fix control bar UI)

Designate the UI type. If not set, it will automatically switch depending on the browser width or device.

              Note

              

Available only with the standard plan.

- The mobile UI provides `touchGestures`, while the PC UI provides `keyboardShortcut`.

```
const player = new ncplayer("player", {
  ui: "mobile", // UI type setting ("auto", "pc", "mobile")
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

## Layout system

By using the layout system, you can declaratively define the placement of control bar buttons, area composition, and insertion of custom components based on JSON. You can separately manage screen environments (PC/mobile/Full screen) and content types (VOD/Live).

              Note

              

- Available only with the standard plan.
- Layout JSON can be visually edited in the [UI Editor](https://vpe-player-editor.web.app/), and the results can be directly applied to the code. For detailed structure and attributes, see the [Layout system guide](https://developer.vpe.naverncp.com/docs/en/layout-system).

### Default layout configuration

Use to `order` define the section order, and place rows in each section. You can insert built-in components or custom elements into the `items` of a row.

```
const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["ProgressBar"] },
        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: ["SettingBtn", "PipBtn", "FullscreenBtn"], wrapper: "Group" },
      ],
    },
  },
};

const player = new ncplayer("player", {
  layout: layout,
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

### Configuration structure

The top-level keys are divided into `pc`, `mobile`, and `fullscreen`, and each environment defines the `vod` and `live` layouts.

```
{
  "pc": {
    "vod": { ... },
    "live": { ... }
  },
  "mobile": {
    "vod": { ... },
    "live": { ... }
  },
  "fullscreen": {
    "vod": { ... },
    "live": { ... }
  }
}
```

### Section and sequence

The `order` array determines the rendering order. The default sections are `top`, `upper`, `center`, `lower`, and `bottom`.

```
{
  "order": ["top", "upper", "center", "lower", "bottom"],
  "top": [
    { "items": ["MetaDesc"] },
    { "wrapper": "Blank", "items": [], "align": "left" },
    { "items": ["ShareBtn"] }
  ],
  "center": [
    { "items": ["BigPlayBtn"], "align": "center" }
  ],
  "bottom": [
    { "items": ["ProgressBar"] },
    { "items": ["PlayBtn", "VolumeBtn", "TimeBtn"], "align": "left" },
    { "items": ["SettingBtn", "PipBtn", "FullscreenBtn"], "align": "right" }
  ]
}
```

### Row configuration

Each section is composed of multiple rows. A row places buttons or components through an `items` array, and adjusts alignment and grouping using `align` and `wrapper`.

| Key | Type | Description |
| --- | --- | --- |
| `items` | `string[]` | List of controls to be placed in a row |
| `align` | `left` \| `center` \| `right` | Content arrangement in rows |
| `wrapper` | `string` | Wrapper type to be applied to a row (e.g.: group, blank) |
| `cap` | `number` | Limit on the number of items displayed within a row |

### Available layout items

`PlayBtn` `VolumeBtn` `TimeBtn` `SubtitleBtn` `FullscreenBtn` `SettingBtn` `PipBtn` `MetaDesc` `BigPlayBtn` `SeekBar` `SettingModal` `DurationBtn` `SkipForwardBtn` `SkipBackBtn` `CurrentTimeBtn` `MuteBtn` `PrevBtn` `NextBtn` `NextPrevBtn` `ShareBtn` `Blank`

### Insert custom HTML element

If you pass HTML strings instead of built-in keys to the `items` array of the layout, you can place custom UI at the desired position within the control bar.

```
// Custom logo HTML
const Logo = `
  <div style="padding:0 15px;">
    <a href="https://example.com" target="_blank">
      <img src="https://example.com/logo.webp" style="height:24px;" alt="Logo" />
    </a>
  </div>`;

const layout = {
  pc: {
    vod: {
      order: ["top", "center", "bottom"],
      top: [{ items: ["MetaDesc"] }],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["PlayBtn", "PrevBtn", "NextBtn"], wrapper: "Group" },
        { items: ["VolumeBtn"], wrapper: "Group" },
        { items: ["TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: [Logo], wrapper: "Group" }, // Custom HTML
        { items: ["SubtitleBtn", "PipBtn", "SettingBtn", "FullscreenBtn"], cap: 2, wrapper: "Group" },
      ],
    },
  },
};

const player = new ncplayer("player", {
  layout: layout,
  playlist: [
    {
      file: "https://example.com/video/master.m3u8",
    },
  ],
});
```

### Runtime layout change

By using the `player.layout()` method, you can dynamically change the layout even during playback.

```
// Change to a new layout
player.layout({
  pc: {
    vod: {
      order: ["center", "bottom"],
      center: [{ items: ["BigPlayBtn"], align: "center" }],
      bottom: [
        { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
        { wrapper: "Blank", items: [] },
        { items: ["FullscreenBtn"], wrapper: "Group" },
      ],
    },
  },
});
```

### Full HTML example

```
<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - layout system</title>

  <!-- Load hls.js/dash.js before the VPE script -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video" style="max-width: 800px; margin: 0 auto;"></div>
  <button id="btn-layout1">Layout 1</button>
  <button id="btn-layout2">Layout 2</button>

  <script>
    var Logo = '<div style="padding:0 15px;"><a href="https://www.ncloud.com" target="_blank"><img src="https://player.vpe.naverncp.com/images/ncp-logo-white.webp" style="height:24px;" /></a></div>';

    var layout1 = {
      pc: {
        vod: {
          order: ["top", "center", "bottom"],
          top: [{ items: ["MetaDesc"] }],
          center: [{ items: ["BigPlayBtn"], align: "center" }],
          bottom: [
            { items: ["PlayBtn", "VolumeBtn", "TimeBtn"], wrapper: "Group" },
            { wrapper: "Blank", items: [] },
            { items: [Logo], wrapper: "Group" },
            { items: ["SettingBtn", "FullscreenBtn"], wrapper: "Group" },
          ],
        },
      },
    };

    var layout2 = {
      pc: {
        vod: {
          order: ["center", "bottom"],
          center: [{ items: ["BigPlayBtn"], align: "center" }],
          bottom: [
            { items: ["PlayBtn", "VolumeBtn"], wrapper: "Group" },
            { wrapper: "Blank", items: [] },
            { items: ["FullscreenBtn"], wrapper: "Group" },
          ],
        },
      },
    };

    var player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDN_DOMAIN/example.m3u8",
          poster: "https://CDN_DOMAIN/poster.jpg",
        },
      ],
      autostart: true,
      muted: true,
      layout: layout1,
    });

    document.getElementById("btn-layout1").addEventListener("click", function() {
      player.layout(layout1);
    });

    document.getElementById("btn-layout2").addEventListener("click", function() {
      player.layout(layout2);
    });
  </script>
</body>
</html>
```