Skip to content

ReferenceText tracks

useActiveTextCues

Hook that returns the cues active now on the text tracks a filter or track definition matches

Import

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

useActiveTextCues returns the cues active at the current time on the tracks a filter or track definition matches, from the media and the app alike, and re-renders when they 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. The text cues feature describes when a cue is active.

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 { defineTextTrack, useActiveTextCues } from '@videojs/react';

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

function QuizOverlay() {
  const [cue] = useActiveTextCues(quizTrack);
  if (!cue) return null;

  return <div className="quiz">{cue.value?.question}</div>;
}

API Reference

With Definition

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

The cues active now on the tracks a track definition matches, typed by the definition. Re-renders when they change.

const [cue] = useActiveTextCues(quizTrack);

Parameters

ParameterTypeDefaultDetails
track*object—

Return Value

readonly Cue[]

With Filter

useActiveTextCues(filter?): readonly MediaTextCue[]

The cues active now on the tracks a filter matches, from the media or the app. Re-renders when they change. A function filter should keep its identity across renders.

Parameters

ParameterTypeDefaultDetails
filterobject—

Return Value

readonly MediaTextCue[]