---
title: "Player UI"
slug: "vpe-tv-player-ui"
updated: 2026-09-17T09:22:39Z
published: 2026-09-17T09:22:39Z
canonical: "guide.ncloud-docs.com/vpe-tv-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

This guide introduces the options for configuring the player UI and the declarative layout system.

## controls

You can set to display the control bar with the `controls` property.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: false, // Hide the control bar
    }}
    onBack={() => navigation.goBack()}
/>
```

## controlBtn

You can set to display individual buttons with the `controlBtn` property. In TV SDK, the properties of `fullscreen` and `pictureInPicture` are not available.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controls: true,
        controlBtn: {
            play: true,
            progressBar: true,
            volume: true,
            times: true,
            setting: true,
            subtitle: true,
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## progressBarColor

You can set the color of the progress bar using the `progressBarColor` property.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        progressBarColor: '#00E0FF',
    }}
    onBack={() => navigation.goBack()}
/>
```

## controlActiveTime

- You can set the time for the control bar to automatically hide using the `controlActiveTime` property. The default value is 3000 ms (3 seconds).

              Note

              

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

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{
        playlist: [{ file: 'https://example.com/video.m3u8' }],
        controlActiveTime: 5000, // Automatically hides after 5 seconds
    }}
    onBack={() => navigation.goBack()}
/>
```

## lang

You can configure the UI language with the `lang` property.

| Value | Language |
| --- | --- |
| ko | Korean (default) |
| en | English |
| ja | 日本語 |

## Remote controller event

TV SDK automatically processes remote controller D-pad inputs.

| Event | Apple TV | Android TV | Behavior |
| --- | --- | --- | --- |
| select | O | O | Confirm/select |
| playPause | O | O | Play/pause |
| up/down | O | O | Control bar display/focus movement |
| left/right | O | O | At `SeekBar`, seeking for ±10 seconds |
| menu | O | X | Back |
| rewind/fastForward | X | O | Rewind/fast forward |

## Layout system

You can customize the control bar UI by using the declarative layout system of the TV SDK.

## Layout structure

It is a declarative layout composed of 5 sections (`top`, `upper`, `center`, `lower`, and `bottom`) and `seekbar`.

## Available items

Items that can be placed in the control bar are as follows:

| Item | Description |
| --- | --- |
| `PlayBtn` | Play/pause/replay |
| `BigPlayBtn` | Central large play + previous/next |
| `BackBtn` | Back |
| `SeekBar` | Seek bar (navigate ±10 seconds with D-pad left/right) |
| `SkipBackBtn / SkipForwardBtn` | ±10-second seek |
| `PrevBtn / NextBtn / NextPrevBtn` | Track navigation |
| `TimeBtn / CurrentTimeBtn / DurationBtn` | Time display (Live indicator when streaming live) |
| `MuteBtn / VolumeBtn` | Mute/volume (mute toggle on TV) |
| `SubtitleBtn` | Subtitle menu |
| `SettingBtn` | Settings menu |
| `MetaDesc` | Video meta information |
| `Blank / BlankBtn` | Empty space |

Items removed from TV are `FullscreenBtn`, `PipBtn`, and `ShareBtn`, and they will be ignored even if included in the layout.

## Custom layout example

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        top: [
            { items: ['BackBtn'], wrapper: 'Group' },
            { items: ['MetaDesc'] },
            { wrapper: 'Blank', items: [] },
        ],
        center: [
            { items: ['BigPlayBtn'], align: 'center' },
        ],
        lower: [
            { wrapper: 'Blank', items: ['SeekBar'], align: 'center' },
        ],
        bottom: [
            { items: ['PlayBtn'], wrapper: 'Group' },
            { items: ['NextPrevBtn'], wrapper: 'Group' },
            { items: ['MuteBtn'], wrapper: 'Group' },
            { items: ['TimeBtn'], wrapper: 'Group' },
            { wrapper: 'Blank', items: [] },
            { items: ['SubtitleBtn', 'SettingBtn'], wrapper: 'Group' },
        ],
    }}
    onBack={() => navigation.goBack()}
/>
```

## VOD/Live variation

You can use different layouts for VOD and Live.

```
<VpePlayer
    accessKey="YOUR_ACCESS_KEY"
    options={{ playlist: [{ file: 'https://example.com/video.m3u8' }] }}
    layout={{
        vod: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['SettingBtn'], wrapper: 'Group' },
            ],
        },
        live: {
            bottom: [
                { items: ['PlayBtn'], wrapper: 'Group' },
                { items: ['TimeBtn'], wrapper: 'Group' },
                { wrapper: 'Blank', items: [] },
                { items: ['MuteBtn'], wrapper: 'Group' },
            ],
        },
    }}
    onBack={() => navigation.goBack()}
/>
```

## Runtime layout change

You can change the layout at runtime through the ref method.

```
const playerRef = useRef<PlayerHandle>(null);

// Partial update (merge=true, default)
playerRef.current?.layout(
    { bottom: [{ items: ['PlayBtn'], wrapper: 'Group' }] },
    true
);

// Total replacement (merge=false)
playerRef.current?.layout(newLayout, false);
```

## Group option

Properties that can be set for each group are as follows:

| Properties | Type | Description |
| --- | --- | --- |
| `items` | string[] | Layout item list |
| `wrapper` | 'Blank', 'Group' | Wrapper type |
| `align` | 'left' , 'right' , 'center' | Alignment |
| `size` | number | Button size (default 88) |