# useCreateTextTrack

Hook that adds a text track to the player while the component is mounted

## Import

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

`useCreateTextTrack` adds a text track to the player while the component is mounted, and removes it on unmount. It takes a [track definition](https://videojs.org/docs/framework/react/reference/api/define-text-track) and the track’s content, or one object describing both. The content holds `cues`, a `src` file to load them from, and a `format` that reads a file in another format. The [text cues feature](https://videojs.org/docs/framework/react/reference/api/feature-text-cues) lists every field.

Added through a definition, the cues are checked against its value type.

**QuizTrack.tsx**

```tsx
import { defineTextTrack, useCreateTextTrack, type TextCueInit } from '@videojs/react';

interface Quiz {
  question: string;
}

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

function QuizTrack({ cues }: { cues: TextCueInit<Quiz>[] }) {
  useCreateTextTrack(quizTrack, { cues });

  return null;
}
```

The hook returns a handle to the track, or `null` before the track is added. The handle’s `addCue(cue)` and `removeCue(id)` change the track’s cues.

## Behavior

The hook removes the track when the component unmounts, and replaces it when the track’s `kind`, `label`, `language`, `cues`, `src`, or `format` changes. Keep `cues` the same array and `format` the same function across renders, such as by memoizing them or defining them outside the component; a new one replaces the track and drops cues added through the old handle.

The track stays through source changes, so give the component a `key` per video to swap tracks with the video. Calling the handle’s `remove()` removes the track until the component remounts or the track is replaced.

Tracks a component adds work with any media, including embeds without text tracks of their own. A `captions` or `subtitles` track is copied into the media, so the browser draws it when it’s selected and the captions menu lists it.

## API Reference

### With Definition

`useCreateTextTrack<Cue extends MediaTextCue>(track, content?): TextTrackHandle<InferCueValue<Cue>> | null`

Add a track defined with `defineTextTrack()` while the component is mounted, and remove it when it unmounts. Its cues are checked against the definition's type. The track stays through source changes. Keep `cues` the same array, and `format` the same function, across renders; a new one replaces the track.

`useCreateTextTrack(quizTrack, { cues });`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `track` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; schema?: StandardSchemaV1 }` | — | The track definition to add. |
| `content` | `{ cues?: readonly TextCueInit<Value>[]; src?: string; format?: ((text: string) => TextCueFormatResult<InferCueValue<Cue>> \| Promise<TextCueFormatResult<InferCueValue<Cue>>>) }` | — | The track's cues. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | The track's id in `textTrackList`. |
| `removed` | `boolean` | Whether the app removed the track, with `remove()` or the store's `removeTextTrack()`. |
| `addCue` | `((cue: TextCueInit<InferCueValue<Cue>>) => void)` | |
| `removeCue` | `((id: string) => void)` | |
| `remove` | `(() => void)` | |

### With Description

`useCreateTextTrack<Value = unknown>(init): TextTrackHandle<Value> | null`

Add a text track while the component is mounted, and remove it when it unmounts. The track stays through source changes. Keep `cues` the same array, and `format` the same function, across renders; a new one replaces the track.

`useCreateTextTrack({ kind: 'metadata', label: 'quiz', cues });`

#### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `init` (required) | `{ kind: 'subtitles' \| 'captions' \| 'descriptions' \| 'chapters' \| 'metadata'; label?: string; language?: string; cues?: readonly TextCueInit<Value>[]; src?: string; format?: ((text: string) => TextCueFormatResult<Value> \| Promise<TextCueFormatResult<Value>>) }` | — | The track to add, with its cues. |

#### Return Value

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | The track's id in `textTrackList`. |
| `removed` | `boolean` | Whether the app removed the track, with `remove()` or the store's `removeTextTrack()`. |
| `addCue` | `((cue: TextCueInit<Value>) => void)` | |
| `removeCue` | `((id: string) => void)` | |
| `remove` | `(() => void)` | |

---

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