# useActiveTextCues

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

## Import

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

`useActiveTextCues` returns the cues active at the current time on the tracks a filter or [track definition](https://videojs.org/docs/framework/react/reference/api/define-text-track) 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](https://videojs.org/docs/framework/react/reference/api/feature-text-cues) 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.

**QuizOverlay.tsx**

```tsx
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

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `track` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | — | The track definition to read. |

#### 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

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `filter` | `{ kind?: TextTrackKind \| readonly TextTrackKind[]; label?: string; language?: string } \| ((track: MediaTextTrack) => boolean)` | — | Picks tracks by kind, label, or language, or with a function. |

#### Return Value

`readonly MediaTextCue[]`

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt