Customization
This section covers how to leverage its compound component pattern, theming system, and gesture controls.
react-native-video-toolkit is designed for high customizability, allowing you to create unique video player experiences. This section covers how to leverage its compound component pattern, theming system, and gesture controls.
Compound Components
The VideoPlayer component uses a compound component pattern, meaning it exposes several sub-components that you can arrange and style as needed. This gives you full control over the player's UI layout.
The compound component pattern allows you to compose custom layouts while maintaining consistent behavior and state management.
Custom Player UI Example
Theming
The library provides a flexible theming system to easily customize colors, fonts, sizing, and other visual elements.
Custom themes should be of type Theme.
Choose a Theme:
Configuration Options
The VideoProvider and VideoPlayer accept various props to configure their behavior.
VideoProvider Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
theme | Theme | No | – | Custom theme object for colors, fonts, sizing, etc. |
config | VideoPlayerConfig | No | – | Configuration options for player behavior. |
components | Partial<VideoComponents> | No | – | Your own sheet, sliders, spinner and press feedback. See Custom Components. |
portalHost | string | No | – | Open the settings sheet in a VideoPortalHost you render, e.g. above your navigator. |
Configuration Example
import { VideoPlayer, VideoProvider } from 'react-native-video-toolkit';
<VideoProvider
config={{
enableScreenRotation: true,
onEnterFullscreen: () => console.log('Entered fullscreen'),
onExitFullscreen: () => console.log('Exited fullscreen'),
onHideControls: () => console.log('Controls hidden'),
onShowControls: () => console.log('Controls shown'),
}}>
<VideoPlayer source={{ uri: 'https://example.com/video.mp4' }}>
<CustomPlayerUI />
</VideoPlayer>
</VideoProvider>;Custom Tracks Example
import { VideoPlayer, VideoProvider } from 'react-native-video-toolkit';
import type { AudioTrack } from 'react-native-video';
import type { CustomVideoTrack } from 'react-native-video-toolkit';
// Define your custom tracks
const customAudioTracks: AudioTrack[] = [
{ index: 0, title: 'English', language: 'en', type: 'audio/mp4a-latm' },
{ index: 1, title: 'Spanish', language: 'es', type: 'audio/mp4a-latm' },
{ index: 2, title: 'French', language: 'fr', type: 'audio/mp4a-latm' },
];
// CustomVideoTrack provides a user-friendly API:
// - label: Display name in the UI (e.g., "Auto", "1080p HD")
// - height: Resolution height in pixels
// - uri: Optional direct URL to the quality stream
const customVideoTracks: CustomVideoTrack[] = [
{ height: 0, label: 'Auto' },
{ height: 1080, label: '1080p Full HD' },
{ height: 720, label: '720p HD' },
{ height: 480, label: '480p SD' },
];
<VideoProvider
config={{
useCustomAudioTracks: true, // Enable custom audio tracks
useCustomVideoTracks: true, // Enable custom video tracks
}}>
<VideoPlayer
source={{ uri: 'https://example.com/video.m3u8' }}
customAudioTracks={customAudioTracks}
customVideoTracks={customVideoTracks}>
<CustomPlayerUI />
</VideoPlayer>
</VideoProvider>;Gestures
The VideoPlayer includes built-in gesture support for common interactions like double-tapping to seek and tapping to toggle controls.
You can also pass gestureProps to extend behavior. This prop accepts GestureHandlerProps.
Gestures Example
import { VideoPlayer, DefaultLayout } from 'react-native-video-toolkit';
import { StyleSheet } from 'react-native';
<VideoPlayer
source={{ uri: 'https://example.com/video.mp4' }}
containerStyle={styles.videoPlayer}
gestureProps={{
onLeftVerticalPan(e) {
console.log('left pan', e);
},
onRightVerticalPan(e) {
console.log('right pan', e);
},
onGlobalVerticalPan(e) {
console.log('global pan', e);
},
}}>
<DefaultLayout />
</VideoPlayer>;
const styles = StyleSheet.create({
videoPlayer: {
width: '100%',
height: 200,
},
});