Skip navigation
Updated: 12.08.2026
Open as Markdown

A component for embedding Kinescope Player in React. It uses an iframe and the IFrame API under the hood. Repository: kinescope/react-kinescope-player .

Installation

npm install @kinescope/react-kinescope-player --save

Quick start

import React from 'react'
import KinescopePlayer from '@kinescope/react-kinescope-player'

function Player() {
  return <KinescopePlayer videoId="VIDEO_ID" />
}

export default Player

Events

function onTimeUpdate({ currentTime }) {
  console.log(currentTime)
}

<KinescopePlayer videoId="VIDEO_ID" onTimeUpdate={onTimeUpdate} />

Methods

Use a ref:

const playerRef = React.createRef()

function handleMuteClick() {
  playerRef.current.mute()
}

<>
  <KinescopePlayer ref={playerRef} videoId="VIDEO_ID" />
  <button onClick={handleMuteClick}>Mute</button>
</>

Next.js

The component uses browser APIs, so disable server-side rendering (SSR):

import dynamic from 'next/dynamic'

const KinescopePlayer = dynamic(
  () => import('@kinescope/react-kinescope-player'),
  { ssr: false }
)

export default function Player() {
  return <KinescopePlayer videoId="VIDEO_ID" />
}

Props

PropTypeDefaultRequired
videoIdstring | string[]yes
classNamestringno
queryQueryno
styleanyno
preloadboolean | 'none' | 'metadata' | 'auto'falseno
titlestringno
subtitlestringno
posterstringno
chaptersChapter[]no
vttVtt[]no
widthnumber | string100%no
heightnumber | string100%no
autoPlayboolean | 'viewable'falseno
autoPauseboolean | 'reset'trueno
loopbooleanfalseno
playsInlinebooleantrueno
mutedbooleanfalseno
language'en' | 'ru'autono
controlsbooleantrueno
mainPlayButtonbooleantrueno
playbackRateButtonbooleanfalseno
textTrackboolean | stringtrueno
externalIdstringno
drmAuthTokenstringno
callToActionCallToAction[]no
bookmarksBookmark[]no
watermarkWatermarkno
playlistOptionsPlaylistOptionsno
themeThemeno
localStorageLocalStoragetrueno

Prop types

Chapter

type Chapter = {
  position: number
  title: string
}

Query

type Query = {
  seek?: number
  duration?: number
  playerId?: string
}

LocalStorage

type LocalStorage =
  | boolean
  | {
      quality?: 'item' | 'global' | boolean
      time?: boolean
      textTrack?: 'item' | 'global' | boolean
    }

Vtt

type Vtt = {
  label: string
  src: string
  srcLang: string
}

CallToAction

type CallToAction = {
  id: string
  title: string
  description?: string
  skipable?: boolean
  buttonStyle?: object
  trigger: {
    percentages: number[]
    timePoints: number[]
    pause: boolean
  }
}

Bookmark

type Bookmark = {
  id: string
  time: number
  title?: string
}

Watermark

type Watermark =
  | string
  | {
      text: string
      mode?: 'random' | 'stripes'
      scale?: number
      displayTimeout?: number | { visible: number; hidden: number }
    }

PlaylistOptions

type PlaylistOptions = {
  autoSwitch?: boolean
  initialItem?: string
  loop?: boolean
}

Theme

type Theme = {
  subtitles?: {
    /** Base font size in em. */
    textScale: number
    textAlign: 'left' | 'center'
    textLength: 'auto' | number
  }
}

Events

EventData
onJSLoad
onJSLoadError
onInit{ playerId: string }
onInitErrorError
onReady{ currentTime, duration, quality }
onQualityChanged{ quality }
onCurrentTrackChanged{ item: { id?: string } }
onSeekChapter{ position: number }
onSizeChanged{ width, height }
onPlay
onPlaying
onWaiting
onPause
onEnded
onTimeUpdate{ currentTime: number }
onProgress{ bufferedTime: number }
onDurationChange{ duration: number }
onVolumeChange{ muted, volume }
onPlaybackRateChange{ playbackRate: number }
onSeeked
onFullscreenChange{ isFullscreen, video }
onPipChange{ isPip: boolean }
onCallAction{ id, title?, type }
onCallBookmark{ id, time, title? }
onError{ error: unknown }
onDestroy

Methods

Call methods through a ref, for example, playerRef.current.play().

MethodParametersResult
isPausedPromise<boolean>
isEndedPromise<boolean>
playPromise<void>
pausePromise<void>
stopPromise<void>
getCurrentTimePromise<number>
getDurationPromise<number>
seekTo(time: number)Promise<void>
isMutedPromise<boolean>
mutePromise<void>
unmutePromise<void>
getVolumePromise<number>
setVolume(value: number)Promise<void>
getPlaybackRatePromise<number>
setPlaybackRate(value: number)Promise<void>
getVideoQualityListPromise<VideoQuality[]>
getVideoQualityPromise<VideoQuality>
setVideoQuality(quality: VideoQuality)Promise<void>
enableTextTrack(lang: string)Promise<void>
disableTextTrackPromise<void>
closeCTAPromise<void>
isFullscreenPromise<boolean>
setFullscreen(fullscreen: boolean)Promise<void>
isPipPromise<boolean>
setPip(pip: boolean)Promise<void>
getPlaylistItemPromise<{ id?: string } | undefined>
switchTo(id: string)Promise<void>
nextPromise<void>
previousPromise<void>

See Control the player for the complete list of IFrame API methods.

Next steps