Video Player

VideoPlayer is a responsive video component with a custom control bar. It renders a native video element and adds consistent play, seek, volume, captions, playback speed and fullscreen controls.

See the live Video Player showcase.

Basic usageCopy Anchor Link

<VideoPlayer
  src="/media/intro.mp4"
  poster="/media/intro-poster.jpg"
  title="Product introduction"
/>

The player fills its container by default and uses a 16 / 9 aspect ratio. Set width, height or style for a fixed or custom size. aspectRatio can be a number or any valid CSS ratio string.

Sources and responsive sizingCopy Anchor Link

Use sources when the browser should choose between different formats. src is convenient for a single source.

<VideoPlayer
  sources={[
    { src: '/media/intro.webm', type: 'video/webm' },
    { src: '/media/intro.mp4', type: 'video/mp4' },
  ]}
  width="100%"
  aspectRatio="21 / 9"
/>

fit controls how the video fills its box: contain preserves the whole frame, cover fills the box and may crop, and fill stretches the frame.

Playback controlsCopy Anchor Link

The custom control bar includes play/pause, a seekable progress bar, current time and duration, volume, mute, playback speed and fullscreen. Each control can be hidden independently. controls={false} hides the control bar and the center play button.

The center action follows the pointer state: a paused video keeps its play action available, while the pause action for a playing video is hidden when the pointer leaves the player. Moving the pointer back over the player reveals the pause action again.

<VideoPlayer
  src="/media/demo.mp4"
  showVolumeControl={false}
  showPlaybackRateControl={false}
  showFullscreenControl={false}
  rates={[0.75, 1, 1.25, 1.5]}
/>

Supported keyboard shortcuts while the player is focused:

• Space or K — play/pause;
• ArrowLeft and ArrowRight — seek five seconds backward/forward;
• M — mute/unmute;
• F — enter/exit fullscreen.

Autoplay and playback stateCopy Anchor Link

autoPlay, loop, muted, playsInline and preload map to the native video behavior. Browsers commonly block autoplay with sound, so autoplay examples should normally also set muted.

<VideoPlayer src="/media/background.mp4" autoPlay muted loop playsInline preload="auto" />

Use defaultVolume and defaultPlaybackRate to set the initial state. onPlay, onPause, onEnded and onTimeUpdate provide lifecycle callbacks.

CaptionsCopy Anchor Link

Pass a track to provide captions or subtitles. The captions button appears automatically when a track exists. Set track.default to show them initially.

<VideoPlayer
  src="/media/demo.mp4"
  track={{
    src: '/media/demo.en.vtt',
    kind: 'subtitles',
    srcLang: 'en',
    label: 'English',
    default: true,
  }}
/>

Loading and fallbackCopy Anchor Link

poster is shown before playback. fallback is rendered when no source exists or the video fails to load. onError is called in addition to the internal error state.

The video itself and the center action both toggle playback. The center action shows Play for a paused video. While the video is playing, the center Pause action is available on hover and is hidden when the pointer leaves the player. The bottom control bar remains independently configurable through controls and the individual show*Control props.

API ReferenceCopy Anchor Link

VideoSourceCopy Anchor Link

VideoTrackCopy Anchor Link

AccessibilityCopy Anchor Link

The player is a focusable region with labelled buttons, labelled range controls, keyboard shortcuts and a native video element. Always provide a meaningful title and poster where appropriate, and provide captions for spoken content.