Skip to content

ReferenceMedia

CloudflareVideo

Video component that plays Cloudflare Stream videos through the Stream player

Cloudflare Stream runs in an embedded player. Its own chrome stays hidden by default, so it drops into a player skin like any other media component; set controls to use Cloudflare’s UI instead.

Import

pnpm add @videojs/cloudflare-video
import { CloudflareVideo } from '@videojs/react/media/cloudflare-video';

Load a source

src takes a raw 32-character video UID, any cloudflarestream.com or videodelivery.net URL, or a signed token. Watch, embed, iframe, manifest, and thumbnail URLs all carry the UID in the same position, and a signed token stands in for the UID wherever one appears.

<CloudflareVideo src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" />

Signed playback

For signed URLs, pass the signed token wherever the UID would go: as the whole src, or inside a Stream URL. Keep your customer subdomain when your URLs name one. Cloudflare serves signed and access-controlled videos only from customer-<code>.cloudflarestream.com, so the element preserves that origin instead of collapsing it onto the shared host.

Behavior

A few things work differently from a native <video> element, because the Stream embed doesn’t expose them:

  • The embed owns text tracks: textTracks stays empty, and engine.cloudflare.defaultTextTrack picks the track to show.
  • Picture-in-picture is unavailable, and the player reports it as unsupported.
  • Fullscreen targets the iframe, so Cloudflare’s own chrome shows in fullscreen.
  • playsInline has no effect: the Stream embed always plays inline.

Examples

Basic Usage

import { CloudflareVideo } from '@videojs/react/media/cloudflare-video';

export default function BasicUsage() {
  return (
    <div className="cloudflare-video">
      <CloudflareVideo src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" controls />
    </div>
  );
}

API Reference

Props

Accepts these Video.js-specific props:

PropTypeDefaultDetails
autoplaybooleanfalse
controlsbooleanfalse
defaultMutedbooleanfalse
loopbooleanfalse
mutedbooleanfalse
playsInlinebooleantrue
posterstring''
preloadMediaPreloadType'metadata'
sourceobjectnull
srcstring''

Engine options

source.engine.cloudflare

Pass Stream player parameters under source.engine.cloudflare, spelled exactly as Cloudflare spells them, plus anything Cloudflare adds next. They’re serialized onto the embed URL untouched, and the embed reads them once, when its URL is built. Media Sources covers how engine options fit into a structured source.

controls, autoplay, loop, muted, preload, and poster come from the props of the same name, so they have no engine.cloudflare spelling.

<CloudflareVideo
  source={{
    src: 'bfbd585059e33391d67b0f1d15fe6ea4',
    engine: { cloudflare: { primaryColor: '#f03e3e', startTime: '5m30s' } },
  }}
/>
OptionTypeDetails
ad-urlstring | undefined
defaultTextTrackstring | undefined
letterboxColorstring | undefined
primaryColorstring | undefined
referrerPolicyReferrerPolicy | undefined
startTimenumber | string | undefined

Refs

ref

Forwards to the rendered <iframe>, an HTMLIFrameElement. The iframe cannot play or seek; use mediaRef for playback.

const ref = useRef<HTMLIFrameElement>(null);

<CloudflareVideo ref={ref} />

mediaRef

Receives the CloudflareAdapter that drives the embed, which exposes media methods and properties such as play() and currentTime. It is set once the adapter has attached to the iframe, so its target is already that iframe, and it is cleared when the iframe unmounts. 

import type { CloudflareAdapter } from '@videojs/cloudflare-video';

const mediaRef = useRef<CloudflareAdapter>(null);

<CloudflareVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();

Events

Handle standard media events with React event props such as onPlay and onTimeUpdate. The adapter dispatches them, not the iframe. For events without a React prop, call addEventListener on the adapter from mediaRef.