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

Available in Classic and VPC

This page describes the options for configuring and setting up the player UI.

## aspectRatio

Use the aspectRatio property to set the aspect ratio of the player. This applies only when the player does not have a fixed size (width, height). The set aspect ratio is maintained even if the container size changes.

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
          aspectRatio: '16/9', // Set the aspect ratio
        }}
    ...
/>
```

## objectFit

Use the objectFit property to set the full screen mode. The following example sets the player to fill the screen while maintaining the playback source ratio:

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
          aspectRatio: '16/9',
          objectFit: 'cover', // Set full screen mode (fit to aspect ratio + fill)
        }}
    ...
/>
```

## controls

Use the controls property to set whether to display the control bar. The following example sets the control bar not to be displayed:

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
          controls: false // Hide control bar (true: Show control bar)
        }}
    ...
/>
```

## controlBtn

Use the controlBtn property to set whether to use the control bar button UI. The following example sets all control bar UI buttons to be displayed.

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
          controls: true, // true: Show buttons, false: Hide buttons
          controlBtn: {
              play: true, // Playback
              progressBar: true // Enable playback bar
              fullscreen: true, // Switch to full screen
              volume: true, // Volume control
              times: true, // Playback time
              setting: true, // Settings
          },
        }}
    ...
/>
```

## progressBarColor

Use the progressBarColor property to set the color of the video seek slider. The following example sets the control bar color to red:

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
           progressBarColor: "#ff0000", // Color code (red)
        }}
    ...
/>
```

## controlActiveTime

Use the controlActiveTime property to set the control bar display time. The following example sets the control bar to be displayed for 3 seconds:

```
<VpePlayer
    ...
    options={{
          playlist: [ //Playback source
              {
                  file: 'https://CDNdomain/example_video_01.mp4'
              },
          ],
          controlActiveTime: 3000, // Set the control bar display time (3000 = 3 seconds)
        }}
    ...
/>
```

## Dynamic modification of control bar UI

You can dynamically modify the button UI according to the video length. For example, if the video length is less than 10 seconds, you can set the full screen, PIP, and settings buttons not to be displayed. The example is as follows:

```
const playerRef = useRef(null);

return(
  <VpePlayer
      ...
      ref={playerRef}
      events={{
           // Dynamically control buttons according to customer needs
          timeupdate: (res) => {  
              if(res.duration < 10){
                  player.current.controlBarBtnStateUpdate ({  //Example: Hide buttons if video length is under 10 seconds
                      fullscreen:false, // Hide full screen button (true: Display full-screen button)
                      pictureInPicture:false, // Hide PIP button (true: Display PIP button)
                      setting:false, // Hide settings button (true: Display Settings button)
                  })
              }
        },
      }}
      options={{
            playlist: [ //Playback source
                {
                    file: 'https://CDNdomain/example_video_01.mp4'
                },
            ],
            controlBtn:{
                play:true,
                fullscreen:true,
                volume:true,
                times:true,
                setting:true,
                subtitle:false,
            },
          }}
      ...
  />
)
```

## Subtitle UI configuration

You can set the size, background, and style of the subtitles.

```
const playerRef = useRef(null);

return(
  <VpePlayer
      ...
      ref={playerRef}
      
      options={{
            playlist: [ //Playback source
                {
                    file: 'https://CDNdomain/example_video_01.mp4'
                },
            ],
            captionStyle: {  // Set caption environment
              fontSize: 12, //Subtitle font size
              color: '#FFFFFF', //Subtitle color
              backgroundColor: 'rgba(0, 0, 0, 0.7)', //Background color
              edgeStyle: 'dropshadow', //Text edge style (dropshadow , raised , depressed , uniform)
            },
          }}
      ...
  />
)
```