React SDK — Ansdev Cloud Docs

The React SDK wraps the underlying Web Component with typed props, ref forwarding, and callback hooks that match React conventions.

Install

npm install @ansdev/player-react

⚠️ Not yet published to npm

The React package ships alongside the v1 stable release of the Player SDK. Until then, drop in the JavaScript SDK via a CDN <script> tag.

Quick start

import { AnsdevPlayer } from '@ansdev/player-react';

export function VideoPage({ videoId, token }: { videoId: string; token: string }) {
  return (
    <AnsdevPlayer
      videoId={videoId}
      playbackToken={token}
      theme={{
        primary: '#22D3EE',
        background: '#0F172A',
      }}
      onPlay={() => console.log('Playing')}
      onEnded={() => console.log('Done')}
    />
  );
}

Props

Prop	Type	Required	Description
`videoId`	string	yes	The video to play
`playbackToken`	string	yes*	Short-lived JWT from your server. *One of `playbackToken` or `apiKey` is required.
`apiKey`	string	no	API key — only acceptable in trusted environments. Prefer `playbackToken`.
`theme`	object	no	Color tokens (see Customization)
`brand`	object	no	`{ name, logo, accent }` for integrator branding
`controls`	object	no	Per-control visibility toggles
`features`	object	no	Feature flags (`keyboardShortcuts`, `pictureInPicture`, etc.)
`autoplay`	boolean	no	Default `false`. Most browsers require `muted={true}` for autoplay to work.
`muted`	boolean	no	Start muted
`startAt`	number	no	Initial playhead in seconds
`className`	string	no	Wrapper class for layout
`style`	CSSProperties	no	Inline style on the wrapper

Callback props

Prop	Signature
`onReady`	`(player: PlayerInstance) => void`
`onPlay`	`() => void`
`onPause`	`() => void`
`onSeek`	`(time: number) => void`
`onEnded`	`() => void`
`onTimeUpdate`	`(time: number) => void`
`onQualityChange`	`(quality: string) => void`
`onError`	`(error: { code: string; message: string }) => void`
`onProgress`	`(progress: { time: number; duration: number }) => void`

TypeScript

Full type definitions ship with the package. No @types/... companion needed.

import type { PlayerInstance, PlayerError } from '@ansdev/player-react';

SSR (Next.js)

The player is client-side only. Disable SSR with a dynamic import:

import dynamic from 'next/dynamic';

const AnsdevPlayer = dynamic(
  () => import('@ansdev/player-react').then((m) => m.AnsdevPlayer),
  { ssr: false },
);

Refs

Forwarded ref returns a PlayerInstance with the same imperative methods as the JavaScript SDK:

import { useRef } from 'react';
import { AnsdevPlayer, type PlayerInstance } from '@ansdev/player-react';

export function ControlledPlayer() {
  const ref = useRef<PlayerInstance>(null);
  return (
    <>
      <AnsdevPlayer ref={ref} videoId="vid_abc123def456" playbackToken="pt_..." />
      <button type="button" onClick={() => ref.current?.play()}>Play</button>
    </>
  );
}

See also: Events · Customization · Keyboard Shortcuts.