Skip to content

ReferenceText tracks

useTextCues

Hook that returns every cue on the text tracks a filter or track definition matches

Import

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

useTextCues returns every cue on the tracks a filter or track definition matches, from the media and the app alike, and re-renders when those cues change. Cues from several tracks are merged in time order. Read through a definition, cues are typed by it, and with a schema, cues whose value fails it are skipped.

While the component is mounted, the hook asks the text cues feature to read the tracks it matches, so it also reads tracks the feature skips by default, such as captions. An inline object filter is compared by its kind, label, and language; keep a function filter’s identity across renders. It returns an empty list when the player has no text cues feature.

import { useActiveTextCues, useTextCues } from '@videojs/react';
import { usePlayer } from '@videojs/react/video';

const captions = { kind: 'captions', language: 'en' } as const;

function Transcript() {
  const store = usePlayer();
  const cues = useTextCues(captions);
  const [active] = useActiveTextCues(captions);

  return (
    <ol className="transcript">
      {cues.map((cue) => (
        <li key={cue.id} aria-current={cue.id === active?.id}>
          <button type="button" onClick={() => store.seek(cue.startTime)}>
            {cue.text}
          </button>
        </li>
      ))}
    </ol>
  );
}

The browser loads a media track’s cues only while the track is showing or hidden, so a transcript of a <track> stays empty while its captions are off. A captions track the app adds with useCreateTextTrack always has its cues.

API Reference

With Definition

useTextCues<Cue extends MediaTextCue>(track): readonly Cue[]

Every cue on the tracks a track definition matches, typed by the definition. Re-renders when those cues change.

Parameters

ParameterTypeDefaultDetails
track*object—

Return Value

readonly Cue[]

With Filter

useTextCues(filter?): readonly MediaTextCue[]

Every cue on the tracks a filter matches, from the media or the app. Re-renders when those cues change. A function filter should keep its identity across renders.

Parameters

ParameterTypeDefaultDetails
filterobject—

Return Value

readonly MediaTextCue[]