VideoPlayer Pro
VideoPlayer gives a video the controls people expect from YouTube or Plyr: a poster and a big play button, a timeline showing what's buffered and, on hover, the time (or a preview frame) under the pointer, play and pause, skip, volume, speed, captions, full screen and picture in picture. The controls fade away while it plays and come back when the pointer moves or the screen is tapped. A spinner shows while it buffers, and a failed video says so with a Try again.
On the web it plays a real <video>, so it streams, seeks and caches as the browser does. React Native has no video of its own, so on iOS and Android you draw one with renderVideo (expo-video's VideoView, below) and these same controls drive it.
import { VideoPlayer } from '@patine-ui/pro';
<VideoPlayer src="/img/demo.mp4" title="React Native Pickers in 40 seconds" tracks={[{ src: '/media/patine-demo.en.vtt', label: 'English', language: 'en' }]} style={{ width: '100%', maxWidth: 760 }} />
Click it to play, then try the keyboard: Space or K plays and pauses, ← → skip 5 seconds, J and L skip 10, ↑ ↓ change the volume, M mutes, F goes full screen, C turns captions on, and 0–9 jump to that tenth.
Example: a course lesson
A course page: the chapter under the player follows the video, and the lesson is marked complete when it ends. onTimeUpdate reports the time about 30 times a second while it plays, and onEnded when it finishes: mark a lesson watched, sync a transcript, start the next video.
<VStack gap="sm" style={{ width: '100%', maxWidth: 640 }}> <VideoPlayer src="/img/demo.mp4" onTimeUpdate={setTime} onEnded={() => setDone(true)} /> {done ? ( <HStack gap="xs" align="center"> <Icon name="checkCircle" size="sm" color="success" /> <Text size="sm" color="success">Lesson complete</Text> </HStack> ) : ( <Text size="sm" color="textSecondary">Chapter: {chapter.title}</Text> )} </VStack>
Captions
tracks takes WebVTT files; the CC button turns the first on and off. Captions draw in the browser's own style, which people can set in their system's accessibility settings.
A phone-sized player
Under 520 points wide the skip buttons, volume slider and picture in picture step aside, so the timeline and the essentials have room. Tapping the video on a phone shows or hides the controls, as native players do; on the web a click plays and pauses.
<VideoPlayer src="/img/demo.mp4" muted style={{ width: 340 }} />
Preview frames
getThumbnail(time) returns an image for a time, shown above the timeline while the pointer moves over it. Most video hosts make these for you: Mux serves https://image.mux.com/{id}/thumbnail.jpg?time={t}, Cloudflare Stream and Bunny have the same.
<VideoPlayer src={hls} getThumbnail={(t) => `https://image.mux.com/${id}/thumbnail.jpg?width=320&time=${Math.round(t)}`} />
iOS and Android with expo-video
renderVideo draws the native view. It gets the src, a style that fills the player, emit to send the native player's state to the controls, and register to hand them a controller.
import { useEffect, useRef } from 'react';
import { useEvent } from 'expo';
import { useVideoPlayer as useExpoVideo, VideoView } from 'expo-video';
import { VideoPlayer } from '@patine-ui/pro';
const ExpoVideo = ({ src, style, emit, register }) => {
const player = useExpoVideo(src, (p) => {
p.timeUpdateEventInterval = 0.25;
});
const view = useRef(null);
useEffect(() => {
register({
play: () => player.play(),
pause: () => player.pause(),
seek: (t) => (player.currentTime = t),
setRate: (r) => (player.playbackRate = r),
setVolume: (v) => (player.volume = v),
setMuted: (m) => (player.muted = m),
enterFullscreen: () => view.current?.enterFullscreen(),
});
const subs = [
player.addListener('playingChange', ({ isPlaying }) => emit({ playing: isPlaying, started: true })),
player.addListener('timeUpdate', ({ currentTime, bufferedPosition }) =>
emit({ currentTime, buffered: [[0, bufferedPosition]], duration: player.duration })
),
player.addListener('statusChange', ({ status, error }) =>
emit({ waiting: status === 'loading', error: status === 'error' ? error?.message ?? 'error' : null })
),
player.addListener('playToEnd', () => emit({ ended: true, playing: false })),
];
return () => {
subs.forEach((s) => s.remove());
register(null);
};
}, [player]);
return <VideoView ref={view} player={player} style={style} nativeControls={false} contentFit="contain" />;
};
<VideoPlayer src={url} poster={poster} renderVideo={(info) => <ExpoVideo {...info} />} />;
The web ignores renderVideo and keeps its <video>, so one component serves all three.
Designs
- Brand, iOS and Material: a round big play button; iOS's timeline has no thumb and thickens when touched, as in the TV app; Material's thumb stays the same size.
- Web: a wide play button and a steady timeline, as the web's players draw them.
The controls are white on a dark shade over every video, whatever the theme; the timeline and buttons take the theme's primary in dark mode.
Accessibility
- The player takes focus and its shortcuts are in its hint. Every control has a name and state: Play or Pause, Mute or Unmute, captions on or off, the current speed.
- The timeline and volume are sliders: screen readers read "1 minute 15 seconds of 3 minutes" and step with the increment and decrement actions.
- Controls don't hide while paused, while the speed menu is open, or while scrubbing. Buttons have 44pt touch targets.
- Fades follow reduce motion.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
src | string | required | The video. On the web, anything <video> plays (MP4, WebM; HLS in Safari). |
poster | string | — | An image before it plays. |
title | string | — | Shown along the top with the controls, and in its label. |
tracks | { src, label, language, default? }[] | — | WebVTT captions (web). |
renderVideo | (info: RenderVideoInfo) => ReactNode | — | Draws the native video on iOS and Android. |
aspectRatio | number | 16 / 9 | Width over height. |
autoPlay, muted, loop | boolean | false | As on <video>. Browsers only autoplay muted. |
rates | number[] | 0.5 to 2 | The speed menu's choices. |
seekStep | number | 5 | Seconds the arrow keys skip. |
hideAfter | number | 2500 | Ms without movement before the controls hide. |
getThumbnail | (time) => string | undefined | — | A preview frame over the timeline. |
onTimeUpdate | (seconds) => void | — | While it plays. |
onEnded | () => void | — | It finished. |
labels | Partial<PlayerLabels> | English | For translation. |
style, theme, design |
Related
- Audio player: podcasts and music, with a waveform and a mini player.
- Image viewer: photos full screen.