# TikTokVideo

Video component that plays TikTok videos through the TikTok embed player

The [TikTok embed player](https://developers.tiktok.com/doc/embed-player) expects portrait video and won’t draw its chrome below 325×578, so the element starts at that size rather than the usual 300×150.

## Import

```bash
pnpm add @videojs/tiktok-video
```

```tsx
import { TikTokVideo } from '@videojs/react/media/tiktok-video';
```

## Load a source

`src` takes a TikTok video URL or a raw numeric video id. The `@user/video/<id>` URLs the app hands out, `share/video/<id>` links, and `player/v1/<id>` embed URLs all work.

```tsx
<TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" />
```

## Controls

TikTok always draws part of its own chrome: the center play button, author header, and social rail are always visible. `controls` adds the progress bar and control buttons on top of those. Without `controls`, the element ignores pointer events, so a [player skin](https://videojs.org/docs/framework/react/guides/skins) above it receives every click.

## Deferred startup

TikTok builds its player lazily: until something starts playback, the embed has no video element, reports a duration of 0, and silently drops commands. The element works around this by starting a muted autoplay and pausing it immediately, so the embed answers play, pause, and seek before the first play.

Two settings opt out. `preload="none"` skips the warm-up, leaving the network untouched until the viewer presses play, and the controls inert until then. `controls` hands playback to TikTok’s own chrome instead.

## Behavior

- Mute works, but there’s no volume control: the embed reports a level but takes no command to set one.
- No playback rate and no text tracks; captions are toggled with `engine.tiktok.closed_caption`.
- `poster` and `playsInline` never reach the embed: it always plays inline and draws the video’s own cover image.
- Changing `controls` or `loop` after the embed is up rebuilds it; rewriting the iframe URL is the only reload TikTok allows.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { TikTokVideo } from '@videojs/react/media/tiktok-video';

export default function BasicUsage() {
  return (
    <div className="tiktok-video">
      <TikTokVideo src="https://www.tiktok.com/@_luwes/video/7527476667770522893" controls />
    </div>
  );
}
```

**App.css**

```css
/* TikTok videos are portrait: the element floors itself at 325x578. */
.tiktok-video {
  display: block;
  width: 325px;
  height: 578px;
  margin-inline: auto;
}
```

## API Reference

### Props

Accepts these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `controls` | `boolean` | `false` | |
| `defaultMuted` | `boolean` | `false` | |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `source` | `{ src?: string; engine?: TikTokSourceEngineConfig } \| null` | `null` | TikTok URL or id in `src`, player params under `engine.tiktok`. Re-derives `src`; equal sources skip reload. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.tiktok`

Pass [TikTok player parameters](https://developers.tiktok.com/doc/embed-player) under `source.engine.tiktok`, spelled exactly as TikTok spells them, each one `0` or `1`, plus anything TikTok adds next. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

`autoplay`, `controls`, `loop`, and `muted` come from the props of the same name, so they have no `engine.tiktok` spelling.

```tsx
<TikTokVideo
  source={{
    src: 'https://www.tiktok.com/@_luwes/video/7527476667770522893',
    engine: { tiktok: { closed_caption: 0, rel: 1 } },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `closed_caption` | `0 \| 1 \| undefined` | Show the closed-caption button. Defaults to `1`. |
| `description` | `0 \| 1 \| undefined` | Show the video description. Defaults to `0`. |
| `fullscreen_button` | `0 \| 1 \| undefined` | Show the fullscreen button. Defaults to `1`. |
| `music_info` | `0 \| 1 \| undefined` | Show the track the video uses. Defaults to `0`. |
| `native_context_menu` | `0 \| 1 \| undefined` | Show the browser's native context menu. Defaults to `1`. |
| `play_button` | `0 \| 1 \| undefined` | Show the play button. Defaults to `1`. |
| `progress_bar` | `0 \| 1 \| undefined` | Show the progress bar. Defaults to `1`. |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a TikTok player parameter. |
| `rel` | `0 \| 1 \| undefined` | Draw related videos from TikTok's recommendations (`1`) or the author's own videos (`0`). Defaults to `1`. |
| `timestamp` | `0 \| 1 \| undefined` | Show the current playback time and duration. Defaults to `1`. |
| `volume_control` | `0 \| 1 \| undefined` | Show the volume control. Defaults to `1`. |

### Ref

Forwards its ref to the rendered `<iframe>`. The ref is an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). Control playback with the component props and player APIs rather than the iframe ref.

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. For native events without a React prop, attach a listener through the ref with `addEventListener`.

---

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