---
title: "Player UX"
slug: "vpe-react-player-ux"
updated: 2026-09-17T09:22:36Z
published: 2026-09-17T09:22:36Z
canonical: "guide.ncloud-docs.com/vpe-react-player-ux"
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 UX

Available in Classic and VPC

It explains how to modify the script code to configure UX-related options.

              Note

              

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

## startMutedInfoNotVisible (display mute status)

You can display the mute status.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        autostart: true,
        muted: true,
        startMutedInfoNotVisible: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## seekingPreview (thumbnail preview)

Thumbnails are provided during section navigation.

              Note

              

- Available only with the standard plan.
- Available only in VODs.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (VOD)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        seekingPreview: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## autoPause (auto-pause when browser is inactive.)

Playback automatically pauses when the tab becomes inactive.

              Note

              

- Available only with the standard plan.
- It does not work on mobile.
- In webapp/webview environments, it does not work.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (VOD)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        autoPause: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## keyboardShortcut (keyboard shortcuts)

You can configure whether keyboard shortcuts are enabled.

              Note

              

Available only with the standard plan.

**Default shortcut**

| Key | Feature |
| --- | --- |
| Space | Play/pause |
| ← → | Jump back/forward 5 seconds |
| ↑ ↓ | Volume adjusted by 5% |
| M | Mute |
| F | Full screen |

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        keyboardShortcut: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## touchGestures (touch gestures)

You can configure whether touch gestures are enabled.

              Note

              

Available only with the standard plan.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        touchGestures: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## visibleWatermark/watermarkText (text watermark)

You can enable the watermark or configure the display text.

              Note

              

- Available only with the standard plan.
- This option can only be applied through console settings.
- Values cannot be changed in code. (They can only be checked within script code.)

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        visibleWatermark: true,
        watermarkText: "Sample watermark",
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## watermarkConfig (detailed settings for text watermark)

You can configure watermark movement, position, transparency, and related options.

**Random movement**

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4) - random movement
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        watermarkConfig: {
          randPosition: true,           // Watermark random movement option
          randPositionInterVal: 5000,  // Random movement interval (ms)
          opacity: 0.4,                // Watermark transparency
        },
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

**Fixed position**

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4) - fixed position
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        watermarkConfig: {
          randPosition: false, // Watermark random movement option
          x: 10,               // Top-left X coordinate (%)
          y: 10,               // Top-left Y coordinate (%)
          opacity: 0.4,        // Watermark transparency
        },
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## iosFullscreenNativeMode (iOS web Full screen mode)

It uses the native Full screen mode of iOS Safari.

              Note

              

- Available only with the standard plan.
- It works only in iOS Safari.
- It is supported in player version 1.1.5 or later.
- The default value is `true`.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        iosFullscreenNativeMode: true,
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
          },
        ],
      }}
    />
  );
}
```

## Custom button

By using `options.icon`, you can replace the default icons in the player control bar with your own images or React components. Icons that are not specified will continue to use the default Material Design icons.

              Note

              

In a UMD environment (static HTML/PHP/JSP), React components cannot be used. Only SVG or PNG image paths (as strings) are supported.

### IconOverrides type

You can pass either `string` or `ReactNode` to each key.

```
type IconOverrides = {
  bigPlay?: string | ReactNode;        // Large play button icon
  play?: string | ReactNode;           // Play icon
  pause?: string | ReactNode;          // Pause icon
  prev?: string | ReactNode;           // Previous track icon
  next?: string | ReactNode;           // Next track icon
  replay?: string | ReactNode;         // Replay icon
  subtitle?: string | ReactNode;       // Subtitles on icon
  subtitleOff?: string | ReactNode;    // Subtitles off icon
  fullscreen?: string | ReactNode;     // Full screen icon
  fullscreenExit?: string | ReactNode; // Full screen off icon
  volumeFull?: string | ReactNode;     // Max volume icon
  volumeMute?: string | ReactNode;     // Mute icon
  volumeMid?: string | ReactNode;      // Medium volume icon
  pip?: string | ReactNode;            // PIP icon
  setting?: string | ReactNode;        // Settings icon
};
```

### Value type

| Type | Examples | Rendering mode |
| --- | --- | --- |
| string | `&quot;/icons/play.svg&quot;` | Rendering with `&lt;img src={url}&gt;` |
| ReactNode | `&lt;FaPlay/&gt;` | Render React components/JSX directly |
| Not assigned | - | Use default material design icons |

### Replace icon with a React component

You can replace icons in JSX using a custom SVG component or an icon library such as `react-icons`.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Definition of custom SVG components
function PlayIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="#ffffff">
      <polygon points="6,3 20,12 6,21" />
    </svg>
  );
}

function PauseIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="#ffffff">
      <rect x="5" y="3" width="4" height="18" />
      <rect x="15" y="3" width="4" height="18" />
    </svg>
  );
}

function FullscreenIcon() {
  return (
    <svg viewBox="0 0 24 24" width="1.5em" height="1.5em" fill="none" stroke="#ffffff" strokeWidth="2">
      <polyline points="15,3 21,3 21,9" />
      <polyline points="9,21 3,21 3,15" />
      <polyline points="21,15 21,21 15,21" />
      <polyline points="3,9 3,3 9,3" />
    </svg>
  );
}

export default function CustomIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          play: <PlayIcon />,
          pause: <PauseIcon />,
          bigPlay: <PlayIcon />,
          fullscreen: <FullscreenIcon />,
          fullscreenExit: <FullscreenExitIcon />,
          setting: <SettingIcon />,
          volumeFull: <VolumeIcon />,
          volumeMute: <VolumeMuteIcon />,
          volumeMid: <VolumeIcon />,
        },
      }}
    />
  );
}
```

`app/player/page.tsx`

### Replace icons with image paths

If you pass an SVG or PNG file path as a string, it will be rendered with an `&lt;img&gt;` tag. This method works in both React and UMD environments.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export default function SvgUrlIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          play: "/icons/play.svg",
          pause: "/icons/pause.svg",
          bigPlay: "/icons/big-play.svg",
          fullscreen: "/icons/fullscreen.svg",
          fullscreenExit: "/icons/fullscreen-exit.svg",
        },
      }}
    />
  );
}
```

### Mixed use

You can use both image paths and React components together to replace icons. If you specify only the icons you need, the rest will remain as the default icons.

```
"use client";
import Hls from "hls.js";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";
import { FaPlay, FaPause } from "react-icons/fa";

export default function MixedIconPlayer() {
  return (
    <VpePlayer
      hls={Hls}
      accessKey="YOUR_ACCESS_KEY"
      options={{
        playlist: [
          { file: "https://example.com/video/master.m3u8" },
        ],
        autostart: true,
        muted: true,
        aspectRatio: "16/9",
        icon: {
          // React component
          play: <FaPlay style={{ fontSize: "1.2rem", color: "#fff" }} />,
          pause: <FaPause style={{ fontSize: "1.2rem", color: "#fff" }} />,
          // Image path
          bigPlay: "/icons/big-play.svg",
          fullscreen: "/icons/fullscreen.svg",
          fullscreenExit: "/icons/fullscreen-exit.svg",
        },
      }}
    />
  );
}
```

`app/player/page.tsx`