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
classNamestring—no
queryQuery—no
styleany—no
preloadboolean | 'none' | 'metadata' | 'auto'falseno
titlestring—no
subtitlestring—no
posterstring—no
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
externalIdstring—no
drmAuthTokenstring—no
callToActionCallToAction[]—no
bookmarksBookmark[]—no
watermarkWatermark—no
playlistOptionsPlaylistOptions—no
themeTheme—no
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
isPaused—Promise<boolean>
isEnded—Promise<boolean>
play—Promise<void>
pause—Promise<void>
stop—Promise<void>
getCurrentTime—Promise<number>
getDuration—Promise<number>
seekTo(time: number)Promise<void>
isMuted—Promise<boolean>
mute—Promise<void>
unmute—Promise<void>
getVolume—Promise<number>
setVolume(value: number)Promise<void>
getPlaybackRate—Promise<number>
setPlaybackRate(value: number)Promise<void>
getVideoQualityList—Promise<VideoQuality[]>
getVideoQuality—Promise<VideoQuality>
setVideoQuality(quality: VideoQuality)Promise<void>
enableTextTrack(lang: string)Promise<void>
disableTextTrack—Promise<void>
closeCTA—Promise<void>
isFullscreen—Promise<boolean>
setFullscreen(fullscreen: boolean)Promise<void>
isPip—Promise<boolean>
setPip(pip: boolean)Promise<void>
getPlaylistItem—Promise<{ id?: string } | undefined>
switchTo(id: string)Promise<void>
next—Promise<void>
previous—Promise<void>

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

Next steps