Player UX

Available in Classic and VPC

Learn about options for configuring and customizing the player UX.

touchGestures (touch gestures)

You can enable the touch gesture feature in mobile UI with the touchGestures property.

<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNdomain/example_video_01.mp4' },
    ],
    touchGestures: true, // Enable touch gestures (default) (false: Disable touch gestures)
  }}
/>

watermarkText (text watermark)

You can set a watermark that can track viewers using the watermarkText property with desired text (user ID + site name, etc.).

<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNdomain/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
  }}
/>

watermarkConfig (detailed settings for text watermark)

When using text watermarks, you can configure detailed options depending on whether the random position is enabled. The detailed options for the watermark can be configured in the NAVER Cloud Platform console.

Enable random position

<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNdomain/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
    watermarkConfig: {
      randPosition: true,          // Enable watermark random position (default)
      randPositionInterVal: 5000,  // Random change interval (default: 3000 ms)
    },
  }}
/>

Disable random position

<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNdomain/example_video_01.mp4' },
    ],
    visibleWatermark: true,
    watermarkText: 'UserId@SiteDomain',
    watermarkConfig: {
      randPosition: false, // Fixed watermark position
      x: 10, // Horizontal position (%)
      y: 2, // Vertical position (%)
      opacity: 0.4, // Transparency (0.1–1)
    },
  }}
/>

Full screen mode

You can choose to develop Full screen either as a modal (Modal) or as a custom Full screen. The modal method cannot be customized but provides basic functionality. Custom Full screen allows you to directly control safe areas and behaviors.

Modal Full screen

<VpePlayer
  options={{
    playlist: [
      { file: 'https://CDNdomain/example_video_01.mp4' },
    ],
    modalFullscreen: true, // true: Modal Full screen, false: Custom Full screen
  }}
/>

Custom Full screen

import { View, StatusBar, ScrollView, Text } from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import { VpePlayer } from 'vpe-react-native';
import React, { useRef, useState } from 'react';
import { useNavigation } from '@react-navigation/native';

export default function App() {
  const navigation = useNavigation();
  const [isFullScreen, setIsFullScreen] = useState(false);
  const playerRef = useRef(null);

  return (
    <SafeAreaProvider>
      <SafeAreaView edges={isFullScreen ? ['none'] : ['top', 'left', 'right']} />
      <StatusBar barStyle={'dark-content'} hidden={isFullScreen} />

      <VpePlayer
        ref={playerRef}
        devTestAppId={'com.vpereactnative.example'}
        accessKey={'YOUR_ACCESS_KEY'}
        platform={'pub'}
        events={{
          fullScreen: (data) => {
            setIsFullScreen(data.isFullScreen);
          },
        }}
        options={{
          playlist: [
            { file: 'https://CDNdomain/example_video_01.mp4' },
          ],
          aspectRatio: '16/9',
          objectFit: 'contain',
          modalFullscreen: false, // Custom Full screen
        }}
      />

      {!isFullScreen && (
        <ScrollView style={{ backgroundColor: '#ffffff' }}>
          <View style={{ padding: 10 }}>
            <Text>Custom Full screen implementation demo</Text>
          </View>
        </ScrollView>
      )}
    </SafeAreaProvider>
  );
}

Custom icon

Supported platforms: Android iOS

The VPE React Native SDK provides an IconOverrides system that allows you to replace all default icons in the Control Bar with custom icons (JSX, remote image URLs, local require images, or functional renderers).

Value type

• ReactNode: Pass JSX directly
• string: Remote image URL → rendered internally with <Image source={{uri}}/>
• number: require('./icon.png') result → local image
• () => ReactNode: Functional for dynamic rendering

Available keys

The following keys are the icon names referenced by the default control components in the control bar.

Replace it with JSX

import { VpePlayer } from 'vpe-react-native';
import { PlayIcon, PauseIcon } from 'phosphor-react-native';

export default function MyPlayer() {
  return (
    <VpePlayer
      accessKey={'YOUR_ACCESS_KEY'}
      options={{
        playlist: [{ file: 'https://CDNdomain/master.m3u8' }],
        icon: {
          play: <PlayIcon size={28} color="#ffffff" weight="fill" />,
          pause: <PauseIcon size={28} color="#ffffff" weight="fill" />,
        },
      }}
    />
  );
}

Replace it with an image

<VpePlayer
  accessKey={'YOUR_ACCESS_KEY'}
  options={{
    playlist: [{ file: 'https://CDNdomain/master.m3u8' }],
    icon: {
      play: 'https://example.com/icons/play.png', // Remote image URL (string)
      pause: require('./assets/pause.png'),        // Local image (require → number)
      fullscreen: () => <MyFullscreenIcon />,      // Functional renderer
    },
  }}
/>