VideoPlayerThe Video Player component allows users to play, pause, and control video content within the app. It supports standard playback functions, accessibility features, and adaptive layouts for different screen sizes.
- Overview
- Dev
Usage Examples
Video Player Structure
The Video Player UI is divided into three main sections (or bars):
1. Top Bar: Contains the close button, video title, video settings, and additional actions like share or cast.
2. Mid Bar: Features the playback controls, including play/pause and seek back/forward buttons.
3. Bottom Bar: Displays the video time track, elapsed/remaining time, sound control, and the fullscreen button. Additionally, custom elements can be rendered beneath the bottom bar.
Video and Player States
| State | Preview |
|---|---|
| Pre Load |  |
| Loading |  |
| Playing |  |
| Playing (hideControls) |  |
| Paused |  |
| Ended |  |
| Offline |  |
| Error |  |
Video Display
| Display | Preview |
|---|---|
| Fit Video The video maintains its original aspect ratio without cropping. Black bars are added if the container's aspect ratio differs. In fullscreen, always use the Fit Container option. |  |
| Fill Video The video scales to fill the container, centering inside it. If aspect ratios differ, cropping may occur to avoid distortion. |  |
| Auto Aspect Ratio The container adapts to the video's size, filling the screen regardless of its orientation. |  |
Player Elements
| Element | Default | On Tap |
|---|---|---|
| Exit full screen Closes portrait and landscape full screen mode |  |  |
| Video quality setting Once set, it’s applied for future videos too |  |  |
| Menu (iOS) Triggers an action sheet with various actions |  |  |
| Menu (Android) Triggers an action sheet with various actions |  |  |
| Share (iOS) Displays the available sharing options |  |  |
| Share (Android) Displays the available sharing options |  |  |
| Chrome Cast Displays the available sharing options |  |  |
| Audio off toggle (mute on) Set by default when “auto start video” is on |  |  |
| Audio on toggle (mute off) Sound is enabled |  |  |
| Expand Enters the full screen mode |  |  |
| Minimize Exits the full screen mode |  |  |
| Replay Replays the video |  |  |
| Seek back (10 seconds) Double tap on the screen left seeks back too |  |  |
| Seek forward (10 seconds) Double tap on the screen right seeks forward too |  |  |
Play/Pause
| Element | Preview |
|---|---|
| Play button |  |
| Pause button |  |
Time
| Element | Preview |
|---|---|
| h:mm:ss |  |
| mm:ss |  |
| m:ss |  |
Custom Elements Examples
| Element | Preview |
|---|---|
| Text |  |
| Toggle Icon |  |
| Custom Actions |  |
Video Player Behavior
Autoplay
Videos can be played manually (default) or automatically (auto-play).
Manual: The user taps the Play/Pause button to start or stop the video.
Auto-Play: The video starts playing automatically when it enters the viewport and pauses when it exits. If a user plays Video B while Video A is already playing, Video A should pause to avoid overlapping playback. Ensure proper communication between multiple videos on the screen to manage this behavior.
Show Video ControlsWhen tapped, video player will expose the player controls for 2.5 seconds.
Sound ControlsTap the Sound icon to toggle audio on or off.
The player should remember the user's last sound setting for future sessions.
In Auto-Play mode, audio is off by default.
Full ScreenFull screen can be entered either by tapping on the “expand” icon, or by tapping on “play” if such behavior is required.
Closing Full ScreenWhen in portrait mode, full screen can be closed either by swiping or by tapping on “close” or “minimize”.
Landscape Full ScreenTilt the phone to switch between portrait and landscape full screen mode. If the player UI is visible, it remains visible after switching.
UI spacing and layout remains consistent in both, portrait and landscape mode.
Seek Back/Seek ForwardTap the video to show player controls.
Tap Seek Back or Seek Forward to skip 10 seconds in either direction.
In landscape full screen mode, the behavior is similar.
Video Quality SettingsVideo quality can be adjusted using quality presets provided by the module.
The player will “remember” your choice for future videos.
Video Playback SpeedVideo playback speed can be adjusted.
The player will “remember” your choice for future videos.
ReplayThe Replay option appears when the video ends.
The “share“ option can be always visible at the top of the player if required.
Offline ErrorPlayback errors typically occur due to weak or no network connection.
A loader appears over the video when the connection is insufficient or temporarily lost (e.g., underground parking, wilderness, elevator). The video resumes automatically when the connection is restored.
If the connection cannot be re-established within 3 seconds, an error message appears.
Cached data (e.g., video thumbnails) remain visible until the screen is refreshed or accessed offline.
Playback ErrorIf there is a technical issue (e.g., broken source or URL), an error appears immediately when attempting to play the video—whether through tapping Play or Auto-Play.
Spec
The Video Player UI is divided into three main sections (or bars):
1. Top Bar: Contains the close button, video title, video settings, and additional actions like share or cast.
2. Mid Bar: Features the playback controls, including play/pause and seek back/forward buttons.
3. Bottom Bar: Displays the video time track, elapsed/remaining time, sound control, and the fullscreen button. Additionally, custom elements can be rendered beneath the bottom bar.
Video Title is limited to 2 lines in portrait mode and a single line in landscape mode.
Track Knob size is 10px and will expand to 20px when tapped.
Video Overlay on tap is bi-directional 60% black and 30% black in the middle.
UsageCode Example
<VideoPlayer
style={styles.video}
muted={isMuted}
paused={isPaused}
forceFullScreenOnPlay={forceFullScreenOnPlay}
onMuteChange={onMuteChange}
title={videoName}
customView={customView}
duration={596}
onBuffer={onBuffer}
onPause={onPause}
onPlay={onPlay}
source={videoSource}
poster={'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg'}
shareOptions={shareOptions}
/>
TIP
This component extends the react-native-video props.
APIThis is the list of additional props for the component