Video player

Use the video player component to enable playback of self-hosted videos

Experimental
Not reviewed for accessibility

On this page

import {VideoPlayer} from '@primer/react-brand'

Examples

Default

<VideoPlayer title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

With poster

<VideoPlayer
  poster="https://primer.github.io/brand/assets/example-poster.png"
  title="GitHub media player"
>
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer
  poster="https://primer.github.io/brand/assets/example-poster.png"
  title="GitHub media player"
>
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

Without branding

<VideoPlayer showBranding={false} title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer showBranding={false} title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer visuallyHiddenTitle title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer visuallyHiddenTitle title="GitHub media player">
  <VideoPlayer.Source src="https://primer.github.io/brand/assets/example.mp4" />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

With some hidden controls

<VideoPlayer
  title="GitHub media player"
  showPlayPauseButton={false}
  showSeekControl={true}
  showCCButton={false}
  showMuteButton={false}
  showVolumeControl={false}
  showFullScreenButton={false}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer
  title="GitHub media player"
  showPlayPauseButton={false}
  showSeekControl={true}
  showCCButton={false}
  showMuteButton={false}
  showVolumeControl={false}
  showFullScreenButton={false}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer title="GitHub media player" showControlsWhenPaused={false}>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer title="GitHub media player" showControlsWhenPaused={false}>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

Minimal

<VideoPlayer
  title="GitHub media player"
  visuallyHiddenTitle
  showBranding={false}
  showControlsWhenPaused={false}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer
  title="GitHub media player"
  visuallyHiddenTitle
  showBranding={false}
  showControlsWhenPaused={false}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

Custom play icon

<VideoPlayer
  title="GitHub media player"
  playIcon={() => <PlayIcon size={96} />}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

<VideoPlayer
  title="GitHub media player"
  playIcon={() => <PlayIcon size={96} />}
>
  <VideoPlayer.Source
    src="https://primer.github.io/brand/assets/example.mp4"
    type="video/mp4"
  />
  <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
</VideoPlayer>

The VideoPlayer component exposes a useVideo hook that can be used to control the video programmatically. To use the hook, the VideoPlayer component must be wrapped in a VideoPlayer.Provider component.

Full documentation for the useVideo hook can be found below.

() => {
  const MyVideoPlayer = () => {
    const {isPlaying, togglePlaying, seek} = useVideo()

    return (
      <Stack direction="vertical">
        <VideoPlayer
          title="GitHub media player"
          showPlayPauseButton={false}
          showSeekControl={false}
          showCCButton={false}
          showMuteButton={false}
          showVolumeControl={false}
          showFullScreenButton={false}
        >
          <VideoPlayer.Source
            src="https://primer.github.io/brand/assets/example.mp4"
            type="video/mp4"
          />
          <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
        </VideoPlayer>
        <Stack direction="horizontal">
          <Button onClick={() => togglePlaying()}>
            {isPlaying ? 'Pause' : 'Play'}
          </Button>
          <Button onClick={() => seek(0)}>Go to start</Button>
          <Button onClick={() => seek((t) => t + 5)}>Skip 5 seconds</Button>
        </Stack>
      </Stack>
    )
  }

  return (
    <VideoPlayer.Provider>
      <MyVideoPlayer />
    </VideoPlayer.Provider>
  )
}

() => {
  const MyVideoPlayer = () => {
    const {isPlaying, togglePlaying, seek} = useVideo()

    return (
      <Stack direction="vertical">
        <VideoPlayer
          title="GitHub media player"
          showPlayPauseButton={false}
          showSeekControl={false}
          showCCButton={false}
          showMuteButton={false}
          showVolumeControl={false}
          showFullScreenButton={false}
        >
          <VideoPlayer.Source
            src="https://primer.github.io/brand/assets/example.mp4"
            type="video/mp4"
          />
          <VideoPlayer.Track src="https://primer.github.io/brand/assets/example.vtt" />
        </VideoPlayer>
        <Stack direction="horizontal">
          <Button onClick={() => togglePlaying()}>
            {isPlaying ? 'Pause' : 'Play'}
          </Button>
          <Button onClick={() => seek(0)}>Go to start</Button>
          <Button onClick={() => seek((t) => t + 5)}>Skip 5 seconds</Button>
        </Stack>
      </Stack>
    )
  }

  return (
    <VideoPlayer.Provider>
      <MyVideoPlayer />
    </VideoPlayer.Provider>
  )
}

useVideo Context

The useVideo context provides a comprehensive API for managing video playback, volume, closed captioning, and fullscreen mode.

The context can be accessed by using the useVideo hook in any component that is a child of VideoPlayer.Provider.

Below is a detailed description of each property and method available in the useVideo context.

Name	Type	Description
`ref`	`RefObject<HTMLVideoElement>`	A reference to the video element.
`isPlaying`	`boolean`	Indicates if the video is currently playing.
`volume`	`number`	The current volume of the video, ranging from 0 to 1.
`isMuted`	`boolean`	Indicates if the video is currently muted.
`volumeBeforeMute`	`number`	The volume of the video before it was muted, allowing for easy unmuting to the previous level.
`duration`	`number`	The total duration of the video in seconds.
`ccEnabled`	`boolean`	Indicates if closed captions are enabled.
`isFullScreen`	`boolean`	Indicates if the video is currently in fullscreen mode.
`play`	`() => void`	Plays the video.
`pause`	`() => void`	Pauses the video.
`togglePlaying`	`() => void`	Toggles between playing and pausing the video.
`setVolume`	`(volumeValOrFn: SetStateAction<number>) => void`	Sets the volume of the video.
`mute`	`() => void`	Mutes the video.
`unmute`	`() => void`	Unmutes the video.
`toggleMute`	`() => void`	Toggles between muting and unmuting the video.
`setDuration`	`(duration: number) => void`	Sets the duration of the video.
`seekToPercent`	`(percent: number) => void`	Seeks the video to a specific percentage of its duration.
`seek`	`(secondsValOrFn: SetStateAction<number>) => void`	Seeks the video to an absolute time, or to a relative time if passed a function.
`enableCC`	`() => void`	Enables closed captions.
`disableCC`	`() => void`	Disables closed captions.
`toggleCC`	`() => void`	Toggles closed captions on and off.
`enterFullScreen`	`() => void`	Enters fullscreen mode.
`exitFullScreen`	`() => void`	Exits fullscreen mode.
`toggleFullScreen`	`() => void`	Toggles between entering and exiting fullscreen mode.

Component props

VideoPlayer Required

VideoPlayer provides a React alternative to the native HTML <video />.

Name	Type	Default	Required	Description
`children`	`React.ReactNode`, `React.ReactNode[]`		`true`	Takes `<VideoPlayer.Source>` and `<VideoPlayer.Track>` elements
`title`	`string`		`true`	Sets the title of the video
`visuallyHiddenTitle`	`boolean`		`false`	Visually hides the title of the video in the upper-left corner
`showBranding`	`boolean`	`true`	`false`	Displays GitHub branding next to video title
`poster`	`string`		`false`	Sets an image as the starting frame for the video element
`className`	`string`		`false`	Sets a custom class on the `<video>` element
`showControlsWhenPaused`	`boolean`	`true`	`false`	Show the video controls when paused
`showPlayPauseButton`	`boolean`	`true`	`false`	Show the play button control
`showSeekControl`	`boolean`	`true`	`false`	Show the seek control
`showCCButton`	`boolean`	`true`	`false`	Show the closed caption toggle control
`showMuteButton`	`boolean`	`true`	`false`	Show the mute button control
`showVolumeControl`	`boolean`	`true`	`false`	Show the volume control
`showFullScreenButton`	`boolean`	`true`	`false`	Show the full screen button control

The component API supports all standard HTML attribute props, while providing some additional behavior as described above.

VideoPlayer.Source Required

VideoPlayer.Source provides a React alternative to the native HTML <source />. The component API supports all standard HTML attribute props.

VideoPlayer.Track Required

VideoPlayer.Track provides a React alternative to the native HTML <track />.

Name	Type	Default	Required	Description
`kind`	`'subtitles'`, `'captions'`, `'descriptions'`, `'chapters'`, `'metadata'`	`'captions'`	`false`	Sets how the text track is meant to be used