useCreateTextTrack

useCreateTextTrack creates a native text track owned by the calling component. It follows the media attached to the current player and removes the track when the component unmounts, its options change, or the player switches media.

The track starts in hidden mode unless you pass a different mode. Hidden tracks load and update cues without asking the browser to render them, which fits chapters and metadata.

Import

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

Usage

The hook returns null until media is available, then an object with the track and addCue and removeCue writers. Write cues through those functions rather than the native track: TextTrack.addCue() fires no event, so useTextCues and useActiveTextCues only refresh for cues written this way. They also wait for the backing native <track> to finish loading, because browsers discard cues added before that point. The hook removes the whole track, including its cues, during cleanup.

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

export function ChapterTrack() {
  const chapters = useCreateTextTrack({
    kind: 'chapters',
    label: 'Sections',
  });

  useEffect(() => {
    if (!chapters) return;

    const introduction = new VTTCue(0, 30, 'Introduction');
    chapters.addCue(introduction);

    return () => chapters.removeCue(introduction);
  }, [chapters]);

  return null;
}

Pass chapters.track to useTextCues or useActiveTextCues to read the cues back.

Use native tracks for WebVTT files

Render the native lowercase <track> element when the cues come from a URL. You do not need a Video.js Track component.

import { Video } from '@videojs/react/video';

<Video>
  <track
    kind="captions"
    src="/captions/en.vtt"
    srcLang="en"
    label="English"
    default
  />
</Video>

Use useCreateTextTrack when your application creates cues in JavaScript. Use useActiveTextTrack to observe a track supplied by markup, a manifest, or another part of the application.