# useTextCues

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

## Import

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

`useTextCues` returns every cue 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 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](https://videojs.org/docs/framework/react/reference/api/feature-text-cues) 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.

**Transcript.tsx**

```tsx
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`](https://videojs.org/docs/framework/react/reference/api/use-create-text-track) 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

| 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

`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

| 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