useCreateTextTrack

Import

import { useCreateTextTrack } from '@videojs/react';

useCreateTextTrack adds a text track to the player while the component is mounted, and removes it on unmount. It takes a track definition and the track’s content, or one object describing both. The content holds cues, a src file to load them from, and a format that reads a file in another format. The text cues feature lists every field.

Added through a definition, the cues are checked against its value type.

import { defineTextTrack, useCreateTextTrack, type TextCueInit } from '@videojs/react';

interface Quiz {
  question: string;
}

const quizTrack = defineTextTrack<Quiz>({ kind: 'metadata', label: 'quiz' });

function QuizTrack({ cues }: { cues: TextCueInit<Quiz>[] }) {
  useCreateTextTrack(quizTrack, { cues });

  return null;
}

The hook returns a handle to the track, or null before the track is added. The handle’s addCue(cue) and removeCue(id) change the track’s cues.

Behavior

The hook removes the track when the component unmounts, and replaces it when the track’s kind, label, language, cues, src, or format changes. Keep cues the same array and format the same function across renders, such as by memoizing them or defining them outside the component; a new one replaces the track and drops cues added through the old handle.

The track stays through source changes, so give the component a key per video to swap tracks with the video. Calling the handle’s remove() removes the track until the component remounts or the track is replaced.

Tracks a component adds work with any media, including embeds without text tracks of their own. A captions or subtitles track is copied into the media, so the browser draws it when it’s selected and the captions menu lists it.

{ kind: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }

{ cues?: readonly TextCueInit<Value>[]; src?: string; format?: ((text: string) => TextCueFormatResult<InferCueValue<Cue>> | Promise<TextCueFormatResult<InferCueValue<Cue>>>) }

((cue: TextCueInit<InferCueValue<Cue>>) => void)

((id: string) => void)

(() => void)

{ kind: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata'; label?: string; language?: string; cues?: readonly TextCueInit<Value>[]; src?: string; format?: ((text: string) => TextCueFormatResult<Value> | Promise<TextCueFormatResult<Value>>) }

((cue: TextCueInit<Value>) => void)

((id: string) => void)

(() => void)