ReferenceMedia

TwitchVideo

Video component that plays Twitch videos and live channels through the Twitch embed player

The Twitch embed player handles both recorded videos and live channels. Its own chrome stays hidden by default, so it drops into a player skin like any other media component; set controls to use Twitch’s UI instead.

Import

pnpm add @videojs/twitch-video

import { TwitchVideo } from '@videojs/react/media/twitch-video';

Load a source

src takes a video URL (twitch.tv/videos/<id>) or a channel URL (twitch.tv/<channel>), with or without the www. and go. hosts. A channel URL plays the channel’s live stream. Clips (clips.twitch.tv) are a different embed and aren’t supported.

<TwitchVideo src="https://www.twitch.tv/videos/106400740" />

Live channels

A channel embed behaves like a live media component:

duration reports Infinity while the stream is live.
Seeking is unavailable: the embed exposes no DVR window.
The stream going away and coming back dispatch offline and online events.
loop never repeats a channel; a live stream doesn’t end.

Parent hostnames

Twitch checks the embedding page’s ancestors against a parent allowlist and won’t play unless the current page is on it. The element always includes your page’s own hostname, so a plain embed needs no setup. When your player is itself framed by other hostnames, name each of them under engine.twitch.parent:

<TwitchVideo
  source={{
    src: 'https://www.twitch.tv/videos/106400740',
    engine: { twitch: { parent: ['embed.example.com'] } },
  }}
/>

Behavior

Volume and mute both work, like a native <video>.
playbackRate is reported but never applied: the embed has no rate command.
loop restarts a finished video from the top; the embed has no loop parameter.
controls is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.

Examples

Basic Usage

import { TwitchVideo } from '@videojs/react/media/twitch-video';

export default function BasicUsage() {
  return (
    <div className="twitch-video">
      <TwitchVideo src="https://www.twitch.tv/videos/106400740" controls />
    </div>
  );
}

.twitch-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}

API Reference

Props

Accepts these Video.js-specific props:

Prop	Type	Default
`autoplay`	`boolean`	`false`
`controls`	`boolean`	`false`
`defaultMuted`	`boolean`	`false`
`loop`	`boolean`	`false`
`muted`	`boolean`	`false`
`playsInline`	`boolean`	`true`
`poster`	`string`	`''`
`preload`	`MediaPreloadType`	`'metadata'`
`source`	`object`	`null`
Description Twitch VOD or channel URL in `src`, plus embed parameters under `engine.twitch`. Replacing it re-derives `src`. Type `{ src?: string; engine?: TwitchSourceEngineConfig } \| null`
`src`	`string`	`''`

Engine options

`source.engine.twitch`

Pass Twitch embed parameters under source.engine.twitch, spelled exactly as Twitch spells them, plus anything Twitch adds next. Media Sources covers how engine options fit into a structured source.

controls, autoplay, and muted come from the props of the same name, and the video or channel comes from src, so none of those have an engine.twitch spelling.

Option	Type	Details
`collection`	`string \| undefined`
Description Collection to play through, starting from the video named by `src`.
`parent`	`string \| readonly string[] \| undefined`
Description Every hostname the embed may be framed by. Twitch checks the frame's ancestors against it and refuses to play when the current page is missing, which is why the page's own hostname is always included on top of this.
`referrerPolicy`	`ReferrerPolicy \| undefined`
Description `referrerpolicy` for the embed iframe. Not a Twitch embed parameter, so it never reaches the URL: the React player applies it to the iframe it renders, and the HTML player reads its own `referrerpolicy` attribute instead.
`time`	`string \| undefined`
Description Start position, spelled the way Twitch spells timestamps: `1h30m10s`.

Refs

`ref`

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

const ref = useRef<HTMLIFrameElement>(null);

<TwitchVideo ref={ref} />

`mediaRef`

Receives the TwitchAdapter 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 { TwitchAdapter } from '@videojs/twitch-video';

const mediaRef = useRef<TwitchAdapter>(null);

<TwitchVideo 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.