api.video React Player component

api.video is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

Project description

The official api.video React Player component.

Getting started


$ npm install --save @api.video/react-player

Basic usage

You can then use the component in your app:

import ApiVideoPlayer from '@api.video/react-player'

// ...

<ApiVideoPlayer video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} style={{ height: '480px' }} />




The following properties are used to configure the player. The value of each of these properties can be changed at any time during the playback.

  id: string;
  live?: boolean;
  token?: string;
id: id of the video to play
token (optional): secret video token
live (optional): true for live videos
stylenoReact.CSSPropertiesCSS style to apply to the player container{}
autoplaynobooleanDefine if the video should start playing as soon as it is loadedfalse
mutednobooleanThe video is mutedfalse
metadatano{ [key: string]: string }Object containing metadata (see example below){}
hidePosternobooleanWeither if the poster image displayed before the first play of the video should be hiddenfalse
chromelessnobooleanChromeless mode: all controls are hiddenfalse
loopnobooleanOnce the video is finished it automatically starts againfalse
hideTitlenobooleanThe video title is hiddenfalse
playbackRatenonumberThe playback rate of the video: 1 for normal, 2 for x2, etc.1
showSubtitlesnobooleanDetermine if the video subtitles should be displayedfalse
volumenonumberThe audio volume. From 0 to 1 (0 = muted, 1 = 100%)1
controlsnoControlName[]List of controls to display. If not specified and chromeless=false, all controls are displayed, see below controlsundefined
themenoPlayerThemeTheme to apply to the player, see below player theme. If not specified, the default theme is usedundefined
responsivenobooleanWeither if the player shoulb be responsive. See below responsivenessfalse
videoStyleObjectFitno"contain" | "cover" | "fill" | "none" | "scale-down"The object-fit CSS value of the video tagundefined
videoStyleTransformnostringThe transform CSS value of the video tag (examples: "rotateY(180deg)")undefined
adsno{adTagUrl: string}see below ads

The controls property let you decide wich controls should be displayed on the player. Here is the list of all available controls: play, seekBackward, seekForward, playbackRate, volume, fullscreen, subtitles, chapters, pictureInPicture, progressBar, chromecast, download, more.


{/* default: all controls are displayed */}
 video={{id: "vi5fv44Hol1jFrCovyktAJS9"}} style={{ height: '480px' }} />

{/* all controls hidden (equivalent to chromeless=true) */}
  video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
  style={{ height: '480px' }}
  controls={[]} />

{ /* only the play button & the unmute one are displayed */}
  video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
  style={{ height: '480px' }}
  controls={["play", "unmute"]}/>
Player theme

The theme property let you customize the color of some elements on the player. Here is the list of customizable elements: text, link, linkHover, trackPlayed, trackUnplayed, trackBackground, backgroundTop, backgroundBottom, backgroundText, linkActive.


{ /* display the text in blue and the progress bar in red */}
  video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
  style={{ height: '480px' }}
    trackPlayed: "#FF0000",
    text: "blue"

Ads can be displayed in the player. To do so, you need to pass the ads option to the sdk constructor. In the ads object, pass the adTagUrl property with the url of the ad tag. The ad tag must be a VAST 2.0 or 3.0 url. For more information about VAST, check the IAB documentation.

Note: ads are displayed using the Google IMA SDK.


With responsive={true}, the player height will be automatically set to match the video with/height ratio, depending on the width of player.


{ /* the player width is 160px and response is true: if the video in a 16/9 one, the height of the player will be automatically set to 90px (160 / (16/9)) */ }
  video={{id: "vi5fv44Hol1jFrCovyktAJS9"}}
  style={{width: "160px"}}
  responsive={true} />


onPlay() => voidCalled when a play event is triggered
onPause() => voidCalled when a pause event is triggered
onControlsDisabled() => voidCalled when a the controls are disabled
onControlsEnabled() => voidCalled when a the controls are enabled
onEnded() => voidCalled when a ended event is triggered
onError() => voidCalled when a error event is triggered
onFirstPlay() => voidCalled when a firstPlay event is triggered
onFullscreenChange() => voidCalled when a fullscreen event is triggered
onMouseEnter() => voidCalled when the mouse enter in the player area
onMouseLeave() => voidCalled when the mouse leave the player area
onPlayerResize() => voidCalled when a resize event is triggered
onQualityChange(resolution: { height: number, width: number }) => voidCalled when the quality of the video changes. The new quality is provided
onVideoSizeRatioChange(ratio: number) => voidCalled when the size ratio of the video changes (ie. when a new video is loaded). The new ratio is provided
onRateChange() => voidCalled when the playback rate changes
onReady() => voidCalled when a ready event is triggered
onSeeking() => voidCalled when a seek event is triggered
onTimeUpdate(currentTime: number) => voidCalled when a timeupdate event is triggered. The current time is provided
onUserActive() => voidCalled when a useractive event is triggered
onUserInactive() => voidCalled when a userinactive event is triggered
onVolumeChange(volume: number) => voidCalled when the volume changes. The volume is provided.
onDurationChange(duration: number) => voidCalled when the duration of the video change. The duration is provided


play()Play the video
pause()Pause the video
seek(time: number)Seek the playback using the specified amount of time (in seconds)
setCurrentTime(time: number)Go to the specified time (in seconds)
requestFullscreen()Request fullscreen mode (this may not work in some cases depending on browser restrictions)
exitFullscreen()Leave fullscreen mode
requestPictureInPicture()Request picture in picture mode (this may not work in some cases depending on browser restrictions)
exitPictureInPicture()Leave picture in picture mode

Use cases

Private videos

To play a private video, add the video view token in the video attribute:

// ...
<ApiVideoPlayer video={{
    id: "vi5fv44Hol1jFrCovyktAJS9",
  token: "e1bdf9a8-da40-421e-87f3-75b15232c531"}}
  style={{ height: '480px' }} />

Defining metadata

// ...
  video={{ id: "vi5fv44Hol1jFrCovyktAJS9" }}
  style={{ height: '480px' }}
  metadata={{"userName": "Alfred"}} />

Define your own controls

const playerRef = useRef<ApiVideoPlayer>(null);

  video={{ id: "vi5jC9kQs2I3PdmVBjgcIg45" }}
  style={{ height: '480px' }}
  <button onClick={() => playerRef.current?.play()}>play</button>
  <button onClick={() => playerRef.current?.pause()}>pause</button>

Was this page helpful?