# Video.js v10 — React Components (complete)

> Every React components page in one file (about 114k tokens). Index with descriptions: https://videojs.org/docs/framework/react/reference/components/llms.txt

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/player -->

# Player

The state boundary — creates a store and broadcasts it to all descendants.

The `Player` is the state boundary of your player. It creates a store and makes it available to every component inside it via context. Every player needs exactly one.

**App.tsx**

```tsx
import { Video, videoFeatures } from '@videojs/react/video';
import { Container, createPlayer } from '@videojs/react';

const { Player } = createPlayer({ features: videoFeatures });

function App() {
  return (
    <Player>
      {/* Everything inside can access the player store */}
      <Container>
        <Video src="video.mp4" />
      </Container>
    </Player>
  );
}
```

## How it’s created

Call `createPlayer()` with a `features` array. It returns `Player`, `usePlayer`, and `useMedia`. Import the shared `Container` separately when building a custom layout.

```tsx
import { Container, createPlayer } from '@videojs/react';
import { videoFeatures } from '@videojs/react/video';

const { Player, usePlayer, useMedia } = createPlayer({
  features: videoFeatures,
});
```

The [features](https://videojs.org/docs/framework/react/guides/features) you pass determine what state is available in the store. `videoFeatures` is a [preset](https://videojs.org/docs/framework/react/guides/presets) that includes playback, volume, fullscreen, and other standard video controls.

- [createPlayer reference](https://videojs.org/docs/framework/react/reference/api/create-player)

## What lives inside it

Everything that needs player state goes inside `Player`: skins, containers, UI components, and your own custom components. Anything inside can access the store.

```tsx
<Player>
  <VideoSkin>           {/* skin — includes container + controls */}
    <Video src="..." /> {/* media component */}
  </VideoSkin>
  <MyCustomOverlay />   {/* your own component — can use usePlayer() */}
</Player>
```

## No visual presence

`Player` renders no DOM element of its own — it’s purely a state wrapper. Put sizing, positioning, borders, backgrounds, and DOM measurements on the [`Container`](https://videojs.org/docs/framework/react/reference/components/player-container), not `Player`.

`Player` is the Provider half of a React Context pair, with [`usePlayer`](https://videojs.org/docs/framework/react/reference/api/use-player) as its consumer, and it renders nothing. If a component needs player state, lift `Player` above it the way you’d lift any Provider: wrapping a page section, a route, or even your whole app in `Player` costs nothing visually and keeps `usePlayer` available wherever you need it.

## Accessing state

Use `usePlayer` to read state or call actions from any component inside `Player`:

**PlayPauseButton.tsx**

```tsx
import { selectPlayback, usePlayer } from '@videojs/react';

function PlayPauseButton() {
  const playback = usePlayer(selectPlayback);
  if (!playback) return null;

  return (
    <button onClick={() => (playback.paused ? playback.play() : playback.pause())}>
      {playback.paused ? 'Play' : 'Pause'}
    </button>
  );
}
```

- [usePlayer reference](https://videojs.org/docs/framework/react/reference/api/use-player)

## Extended player layouts

The player’s scope can extend beyond the fullscreen target. Playlists, transcripts, sidebars, and other supplementary UI can live inside `Player` but outside `Container`. They still have full access to the store, but they won’t go fullscreen with the video.

```tsx
<Player>
  <Container>
    <Video src="video.mp4" />
    <Controls.Root>          {/* goes fullscreen with the video */}
      <Controls.Content>{/* ... */}</Controls.Content>
    </Controls.Root>
  </Container>

  <Transcript />          {/* outside container — still has store access */}
  <PlaylistSidebar />     {/* outside container — still has store access */}
</Player>
```

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/player-container -->

# Container

The player's visual and interaction surface for layout, fullscreen, focus, and user activity.

The `Container` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey components a shared interaction surface. It lives inside a [`Player`](https://videojs.org/docs/framework/react/reference/components/player).

```tsx
<Player>
  <Container>
    <Video src="video.mp4" />
    <Controls.Root>
      <Controls.Content>{/* ... */}</Controls.Content>
    </Controls.Root>
  </Container>
</Player>
```

## How it’s created

Import `Container` from the main React package. It connects to whichever `Player` contains it, so it does not need to be created for a specific feature set.

```tsx
import { Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });
```

- [`createPlayer` reference](https://videojs.org/docs/framework/react/reference/api/create-player)

## What it does

### Layout and fullscreen

The container is the visual box around your media and controls. Put sizing, aspect ratio, positioning, and visual boundaries here — on `Container`, not `Player`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.

```tsx
<Container style={{ position: 'relative', width: 640, aspectRatio: '16/9' }}>
  <Video src="video.mp4" />
  <Controls.Root>
    <Controls.Content>{/* ... */}</Controls.Content>
  </Controls.Root>
</Container>
```

When the user goes fullscreen, the **container** goes fullscreen — not the video element. This keeps controls and other UI visible on top of the video, since they’re children of the container.

React media components such as `MuxVideo` render a native media element, so the media itself has a box. The container remains the shared layout and fullscreen target for the media and its overlays.

### Media attachment

Media discovery is handled by `Player`, not `Container`. When a media component like `<Video>` registers itself via context, `Player` wires it to the store and all of the player’s features.

### Interaction surface

The container is where user intent enters the player. It listens for physical interaction on its surface and translates that into player behavior:

- **User activity** — Mouse movement, touch, and keyboard activity within the container drive idle detection. This is how controls know when to show and hide.
- **Gestures** — Tap and double-tap actions, optionally limited by pointer type and left, center, or right region. Configured via the [`Gesture`](https://videojs.org/docs/framework/react/reference/components/gesture) component.
- **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `Hotkey` component.

### Popup coordination

Each container owns one popup group. Opening a root [menu](https://videojs.org/docs/framework/react/reference/components/menu) or [popover](https://videojs.org/docs/framework/react/reference/components/popover) closes the previously open popup in that container. A popup rendered outside the container still manages its own open state, but it does not participate in the container’s group.

## Relationship to skins

A [skin](https://videojs.org/docs/framework/react/guides/skins) is a container plus UI controls. When you use a packaged skin, the container is built in — you don’t need to add one yourself.

Style `VideoSkin` for the player’s outer size and aspect ratio. Its `skin.css` import makes the built-in container fill that space and positions the media, controls, poster, and overlays.

If you omit `VideoSkin` to build custom UI, render and style `Container` yourself. See [Layout and fullscreen](https://videojs.org/docs/framework/react/reference/components/player-container#layout-and-fullscreen) for the complete layout example.

## Inside vs. outside the container

[`Player`](https://videojs.org/docs/framework/react/reference/components/player) gives components access to state and actions. `Container` layers on physical behaviors — fullscreen, activity detection, and gesture handling. Components work in both places; the container just adds those extras.

```tsx
<Player>
  <Container>
    <Video src="video.mp4" />
    <Controls.Root>          {/* fullscreen, activity detection, gestures */}
      <Controls.Content>{/* ... */}</Controls.Content>
    </Controls.Root>
  </Container>

  <Transcript />          {/* state & actions, but no container behaviors */}
  <PlaylistSidebar />     {/* state & actions, but no container behaviors */}
</Player>
```

A play button outside the container still reads playback state and can toggle play/pause — it just won’t go fullscreen with the player or respond to the container’s idle state.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/controls -->

# Controls

Container component for composing and auto-hiding video player controls on user interaction

## Import

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

## Anatomy

Import the component and assemble its parts:

```tsx
<Controls.Root>
  <Controls.Backdrop />
  <Controls.Content>
    <Controls.Group />
  </Controls.Content>
</Controls.Root>
```

## Behavior

If the user is active, or if the video is paused, this component will show controls. Otherwise, it will hide them after a short delay.

User activity is tracked via pointer movement, keyboard input, and focus events on the player container. On touch devices, a quick tap toggles visibility. `mouseleave` immediately sets the user as inactive.

`visibility` selects between the two modes. The default, `auto`, follows the player’s controls visibility state as described above. `always` keeps the controls visible and reports the user as active regardless of playback or idle state, and works without the controls feature. The idle delay itself is not configurable.

```tsx
<Controls.Root visibility="always">
  <Controls.Content>...</Controls.Content>
</Controls.Root>
```

## Styling

`Controls.Root` is a state and context provider. `Controls.Content` renders the interactive controls surface and receives its DOM props, ref, and controls state data attributes.

`Controls.Backdrop` is an optional presentational sibling of `Controls.Content`. It receives the same controls state data attributes, allowing its styling and transitions to be authored independently from the controls surface.

The controls parts ship no styles. These example rules provide click-through and fade behavior:

React renders `<div>` elements. Add a `className` to style them:

```css
/* Click-through: clicks pass through controls to video beneath */
.controls {
  pointer-events: none;
}

.controls-group {
  pointer-events: auto;
}

.controls-backdrop {
  position: absolute;
  inset: 0;
  transition: opacity 0.35s;
}

/* Fade transition */
.controls {
  transition: opacity 0.25s;
}

.controls:not([data-visible]) {
  opacity: 0;
}

.controls-backdrop:not([data-visible]) {
  opacity: 0;
}
```

## Accessibility

`Controls.Root` renders no element. No ARIA role is applied to `Controls.Content` because it is a layout surface, not a landmark. `Controls.Backdrop` is always hidden from assistive technology. `Controls.Group` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, Controls, createPlayer, PlayButton, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />

        <Controls.Root>
          <Controls.Backdrop className="controls-backdrop" />
          <Controls.Content className="media-controls">
            <Controls.Group className="controls-group" aria-label="Playback controls">
              <PlayButton
                className="button"
                render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
              />

              <Time.Value type="current" className="time" />
            </Controls.Group>
          </Controls.Content>
        </Controls.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-controls {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: flex-end;
  padding: 12px;
  pointer-events: none;
  transition: opacity 0.25s;
}

.controls-backdrop {
  position: absolute;
  inset: 0;
  pointer-events: none;
  background: linear-gradient(to top, rgba(0, 0, 0, 0.45), transparent 45%);
  opacity: 1;
  transition: opacity 0.35s;
}

.controls-backdrop:not([data-visible]),
.media-controls:not([data-visible]):not(:has(:focus-visible)) {
  opacity: 0;
}

.controls-group {
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  pointer-events: auto;
}

.time {
  display: inline-flex;
  gap: 4px;
  align-items: center;
  padding-block: 8px;
  padding-inline: 16px;
  font-size: 14px;
  color: black;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.25);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.button {
  padding-block: 8px;
  padding-inline: 16px;
  font-size: 14px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.25);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Root

Manages controls state and provides it to the compound parts. Does not render an element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visibility` | `'auto' \| 'always'` | `'auto'` | Whether controls follow player visibility state or remain visible. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | Whether the controls are visible. |
| `userActive` | `boolean` | Whether the user has recently interacted with the player. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present when controls are visible. |
| `data-user-active` | Present when the user has recently interacted. |

### Backdrop

Presentational layer behind player controls. Renders a `<div>` with the controls state data attributes so skins can style it without reaching across sibling components.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ControlsState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ControlsState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ControlsState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present when controls are visible. |
| `data-user-active` | Present when the user has recently interacted. |

### Content

Renders the interactive controls surface.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ControlsState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ControlsState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ControlsState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present when controls are visible. |
| `data-user-active` | Present when the user has recently interacted. |

### Group

Layout group for related controls; sets `role="group"` when labeled.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ControlsState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ControlsState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ControlsState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present when controls are visible. |
| `data-user-active` | Present when the user has recently interacted. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/video-skin -->

# VideoSkin

The video preset's default skin with the modern, frosted look

The default skin of the video preset: the control layout for on-demand video with the modern, frosted look. [NeutralVideoSkin](https://videojs.org/docs/framework/react/reference/components/video-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the video preset ships.

## Import

```tsx
import { VideoSkin } from '@videojs/react/video';
import '@videojs/react/video/skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<VideoPlayer>
  <VideoSkin>
    <Video />
  </VideoSkin>
</VideoPlayer>
```

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. Pass `renderThumbnail` to replace it with your own image, for example to set `crossOrigin`, `loading`, or `fetchPriority`.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/react/guides/thumbnails) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Video, VideoPlayer, VideoSkin } from '@videojs/react/video';

import '@videojs/react/video/skin.css';

export default function BasicUsage() {
  return (
    <VideoPlayer poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
      <VideoSkin className="react-video-skin-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline crossOrigin="anonymous">
          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
        </Video>
      </VideoSkin>
    </VideoPlayer>
  );
}
```

**App.css**

```css
.react-video-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/video-neutral-skin -->

# NeutralVideoSkin

The video preset's visually lighter skin, closer to a classic control bar

The neutral skin of the video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. The [default video skin](https://videojs.org/docs/framework/react/reference/components/video-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the video preset ships.

## Import

```tsx
import { NeutralVideoSkin } from '@videojs/react/video';
import '@videojs/react/video/neutral-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<VideoPlayer>
  <NeutralVideoSkin>
    <Video />
  </NeutralVideoSkin>
</VideoPlayer>
```

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. Pass `renderThumbnail` to replace it with your own image, for example to set `crossOrigin`, `loading`, or `fetchPriority`.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/react/guides/thumbnails) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { NeutralVideoSkin, Video, VideoPlayer } from '@videojs/react/video';

import '@videojs/react/video/neutral-skin.css';

export default function BasicUsage() {
  return (
    <VideoPlayer poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
      <NeutralVideoSkin className="react-video-neutral-skin-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline crossOrigin="anonymous">
          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
        </Video>
      </NeutralVideoSkin>
    </VideoPlayer>
  );
}
```

**App.css**

```css
.react-video-neutral-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/video-compat-skin -->

# CompatVideoSkin

A video skin designed for broader browser compatibility

The Compat skin of the video preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. Its time slider supports chapter segments and thumbnail previews. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins) to install and edit its source.

## Import

```tsx
import { CompatVideoSkin } from '@videojs/react/video';
import '@videojs/react/video/compat-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<VideoPlayer>
  <CompatVideoSkin>
    <Video />
  </CompatVideoSkin>
</VideoPlayer>
```

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. Pass `renderThumbnail` to replace it with your own image, for example to set `crossOrigin`, `loading`, or `fetchPriority`.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/react/guides/thumbnails) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CompatVideoSkin, Video, VideoPlayer } from '@videojs/react/video';

import '@videojs/react/video/compat-skin.css';

export default function BasicUsage() {
  return (
    <VideoPlayer poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
      <CompatVideoSkin className="react-video-compat-skin-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline crossOrigin="anonymous">
          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
        </Video>
      </CompatVideoSkin>
    </VideoPlayer>
  );
}
```

**App.css**

```css
.react-video-compat-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/audio-skin -->

# AudioSkin

The audio preset's default skin with the modern, frosted look

The default skin of the audio preset: the control layout for on-demand audio with the modern, frosted look. [NeutralAudioSkin](https://videojs.org/docs/framework/react/reference/components/audio-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the audio preset ships.

## Import

```tsx
import { AudioSkin } from '@videojs/react/audio';
import '@videojs/react/audio/skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<AudioPlayer>
  <AudioSkin>
    <Audio />
  </AudioSkin>
</AudioPlayer>
```

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Audio, AudioPlayer, AudioSkin } from '@videojs/react/audio';

import '@videojs/react/audio/skin.css';

export default function BasicUsage() {
  return (
    <AudioPlayer>
      <AudioSkin className="react-audio-skin-basic">
        <Audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossOrigin="anonymous" />
      </AudioSkin>
    </AudioPlayer>
  );
}
```

**App.css**

```css
.react-audio-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/audio-neutral-skin -->

# NeutralAudioSkin

The audio preset's visually lighter skin, closer to a classic control bar

The neutral skin of the audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. [AudioSkin](https://videojs.org/docs/framework/react/reference/components/audio-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the audio preset ships.

## Import

```tsx
import { NeutralAudioSkin } from '@videojs/react/audio';
import '@videojs/react/audio/neutral-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<AudioPlayer>
  <NeutralAudioSkin>
    <Audio />
  </NeutralAudioSkin>
</AudioPlayer>
```

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Audio, AudioPlayer, NeutralAudioSkin } from '@videojs/react/audio';

import '@videojs/react/audio/neutral-skin.css';

export default function BasicUsage() {
  return (
    <AudioPlayer>
      <NeutralAudioSkin className="react-audio-neutral-skin-basic">
        <Audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossOrigin="anonymous" />
      </NeutralAudioSkin>
    </AudioPlayer>
  );
}
```

**App.css**

```css
.react-audio-neutral-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/audio-compat-skin -->

# CompatAudioSkin

An audio skin designed for broader browser compatibility

The Compat skin of the audio preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. Its time slider supports chapter segments and thumbnail previews. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins) to install and edit its source.

## Import

```tsx
import { CompatAudioSkin } from '@videojs/react/audio';
import '@videojs/react/audio/compat-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<AudioPlayer>
  <CompatAudioSkin>
    <Audio />
  </CompatAudioSkin>
</AudioPlayer>
```

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Audio, AudioPlayer, CompatAudioSkin } from '@videojs/react/audio';

import '@videojs/react/audio/compat-skin.css';

export default function BasicUsage() {
  return (
    <AudioPlayer>
      <CompatAudioSkin className="react-audio-compat-skin-basic">
        <Audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossOrigin="anonymous" />
      </CompatAudioSkin>
    </AudioPlayer>
  );
}
```

**App.css**

```css
.react-audio-compat-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-video-skin -->

# LiveVideoSkin

The live video preset's default skin, which swaps time controls for a Live button

The default skin of the live video preset: the video layout with the time slider and time displays swapped for a Live button. [NeutralLiveVideoSkin](https://videojs.org/docs/framework/react/reference/components/live-video-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the live video preset ships.

## Import

```tsx
import { LiveVideoSkin } from '@videojs/react/live-video';
import '@videojs/react/live-video/skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveVideoPlayer>
  <LiveVideoSkin>
    <HlsVideo />
  </LiveVideoSkin>
</LiveVideoPlayer>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/react/reference/components/hls-video) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { LiveVideoPlayer, LiveVideoSkin } from '@videojs/react/live-video';
import { HlsVideo } from '@videojs/react/media/hls-video';

import '@videojs/react/live-video/skin.css';

export default function BasicUsage() {
  return (
    <LiveVideoPlayer>
      <LiveVideoSkin className="react-live-video-skin-basic">
        <HlsVideo src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsInline crossOrigin="anonymous" />
      </LiveVideoSkin>
    </LiveVideoPlayer>
  );
}
```

**App.css**

```css
.react-live-video-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-video-neutral-skin -->

# NeutralLiveVideoSkin

The live video preset's visually lighter skin, closer to a classic control bar

The neutral skin of the live video preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveVideoSkin](https://videojs.org/docs/framework/react/reference/components/live-video-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the live video preset ships.

## Import

```tsx
import { NeutralLiveVideoSkin } from '@videojs/react/live-video';
import '@videojs/react/live-video/neutral-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveVideoPlayer>
  <NeutralLiveVideoSkin>
    <HlsVideo />
  </NeutralLiveVideoSkin>
</LiveVideoPlayer>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/react/reference/components/hls-video) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { LiveVideoPlayer, NeutralLiveVideoSkin } from '@videojs/react/live-video';
import { HlsVideo } from '@videojs/react/media/hls-video';

import '@videojs/react/live-video/neutral-skin.css';

export default function BasicUsage() {
  return (
    <LiveVideoPlayer>
      <NeutralLiveVideoSkin className="react-live-video-neutral-skin-basic">
        <HlsVideo src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsInline crossOrigin="anonymous" />
      </NeutralLiveVideoSkin>
    </LiveVideoPlayer>
  );
}
```

**App.css**

```css
.react-live-video-neutral-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-video-compat-skin -->

# CompatLiveVideoSkin

A live video skin designed for broader browser compatibility

The Compat skin of the live video preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. It shows a Live button in place of time controls. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins) to install and edit its source.

## Import

```tsx
import { CompatLiveVideoSkin } from '@videojs/react/live-video';
import '@videojs/react/live-video/compat-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveVideoPlayer>
  <CompatLiveVideoSkin>
    <HlsVideo />
  </CompatLiveVideoSkin>
</LiveVideoPlayer>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/react/reference/components/hls-video) because most browsers can’t play HLS streams with a plain `<video>`. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. Pass `renderPoster` to replace it with your own component.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/react/guides/poster) for complete examples.

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CompatLiveVideoSkin, LiveVideoPlayer } from '@videojs/react/live-video';
import { HlsVideo } from '@videojs/react/media/hls-video';

import '@videojs/react/live-video/compat-skin.css';

export default function BasicUsage() {
  return (
    <LiveVideoPlayer>
      <CompatLiveVideoSkin className="react-live-video-compat-skin-basic">
        <HlsVideo src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsInline crossOrigin="anonymous" />
      </CompatLiveVideoSkin>
    </LiveVideoPlayer>
  );
}
```

**App.css**

```css
.react-live-video-compat-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-audio-skin -->

# LiveAudioSkin

The live audio preset's default skin, which swaps time controls for a Live button

The default skin of the live audio preset: the audio layout with the time slider and time displays swapped for a Live button. [NeutralLiveAudioSkin](https://videojs.org/docs/framework/react/reference/components/live-audio-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the live audio preset ships.

## Import

```tsx
import { LiveAudioSkin } from '@videojs/react/live-audio';
import '@videojs/react/live-audio/skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveAudioPlayer>
  <LiveAudioSkin>
    <MuxAudio />
  </LiveAudioSkin>
</LiveAudioPlayer>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/react/reference/components/mux-audio): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { LiveAudioPlayer, LiveAudioSkin } from '@videojs/react/live-audio';
import { MuxAudio } from '@videojs/react/media/mux-audio';

import '@videojs/react/live-audio/skin.css';

export default function BasicUsage() {
  return (
    <LiveAudioPlayer>
      <LiveAudioSkin className="react-live-audio-skin-basic">
        <MuxAudio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossOrigin="anonymous" />
      </LiveAudioSkin>
    </LiveAudioPlayer>
  );
}
```

**App.css**

```css
.react-live-audio-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-audio-neutral-skin -->

# NeutralLiveAudioSkin

The live audio preset's visually lighter skin, closer to a classic control bar

The neutral skin of the live audio preset: the same player and the same controls in a visually lighter design, closer to a classic control bar. Like the default skin, it shows a Live button in place of time controls. [LiveAudioSkin](https://videojs.org/docs/framework/react/reference/components/live-audio-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the live audio preset ships.

## Import

```tsx
import { NeutralLiveAudioSkin } from '@videojs/react/live-audio';
import '@videojs/react/live-audio/neutral-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveAudioPlayer>
  <NeutralLiveAudioSkin>
    <MuxAudio />
  </NeutralLiveAudioSkin>
</LiveAudioPlayer>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/react/reference/components/mux-audio): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { LiveAudioPlayer, NeutralLiveAudioSkin } from '@videojs/react/live-audio';
import { MuxAudio } from '@videojs/react/media/mux-audio';

import '@videojs/react/live-audio/neutral-skin.css';

export default function BasicUsage() {
  return (
    <LiveAudioPlayer>
      <NeutralLiveAudioSkin className="react-live-audio-neutral-skin-basic">
        <MuxAudio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossOrigin="anonymous" />
      </NeutralLiveAudioSkin>
    </LiveAudioPlayer>
  );
}
```

**App.css**

```css
.react-live-audio-neutral-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-audio-compat-skin -->

# CompatLiveAudioSkin

A live audio skin designed for broader browser compatibility

The Compat skin of the live audio preset provides basic controls and plain surfaces, with broader browser compatibility as its design goal. It shows a Live button in place of time controls. See [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins) to install and edit its source.

## Import

```tsx
import { CompatLiveAudioSkin } from '@videojs/react/live-audio';
import '@videojs/react/live-audio/compat-skin.css';
```

## Anatomy

The skin goes between the player and the media component. It renders its controls around the media.

```tsx
<LiveAudioPlayer>
  <CompatLiveAudioSkin>
    <MuxAudio />
  </CompatLiveAudioSkin>
</LiveAudioPlayer>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/react/reference/components/mux-audio): a plain `<audio>` can’t play HLS in most browsers, and this element reports the live playback state the skin’s Live button needs. See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams).

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CompatLiveAudioSkin, LiveAudioPlayer } from '@videojs/react/live-audio';
import { MuxAudio } from '@videojs/react/media/mux-audio';

import '@videojs/react/live-audio/compat-skin.css';

export default function BasicUsage() {
  return (
    <LiveAudioPlayer>
      <CompatLiveAudioSkin className="react-live-audio-compat-skin-basic">
        <MuxAudio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossOrigin="anonymous" />
      </CompatLiveAudioSkin>
    </LiveAudioPlayer>
  );
}
```

**App.css**

```css
.react-live-audio-compat-skin-basic {
  width: 100%;
}
```

## Own the UI

Packaged skins keep their controls and layout inside Video.js. When you need to add, remove, rearrange, or deeply restyle controls, use Shadcn to add the skin source to your project. Its components, layout, styles, and interactions become local files you can change.

- [Install Video.js with Shadcn](https://videojs.org/docs/guides/installation/shadcn?framework=react#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/background-video-skin -->

# BackgroundVideoSkin

The background preset's chrome-less skin for ambient video

The only skin of the background preset: a chrome-less surface that sizes ambient video with no visible controls. See [Skins](https://videojs.org/docs/framework/react/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/react/guides/presets) for what the background preset ships.

## Import

```tsx
import { BackgroundVideoSkin } from '@videojs/react/background';
import '@videojs/react/background/skin.css';
```

## Anatomy

The skin goes between the player and the media component. It sizes the ambient video and renders no visible controls.

```tsx
<BackgroundVideoPlayer>
  <BackgroundVideoSkin>
    <BackgroundVideo />
  </BackgroundVideoSkin>
</BackgroundVideoPlayer>
```

## Styling

Packaged skins style themselves and expose a small set of public CSS custom properties. Everything else inside the skin is private and may change between releases. [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-a-packaged-skin) documents the properties.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';

import '@videojs/react/background/skin.css';

export default function BasicUsage() {
  return (
    <BackgroundVideoPlayer>
      <BackgroundVideoSkin className="react-background-video-skin-basic">
        <BackgroundVideo src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4" />
      </BackgroundVideoSkin>
    </BackgroundVideoPlayer>
  );
}
```

**App.css**

```css
.react-background-video-skin-basic {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## Own the UI

Owning the UI means keeping its components, layout, styles, and interactions as local files you can change. The [Shadcn installation guide](https://videojs.org/docs/guides/installation/shadcn?framework=react) adds that source for supported skins. The registry does not provide background video skin source because it has no control UI. Follow [Add a background video](https://videojs.org/docs/framework/react/guides/background-video) to compose the media directly, then add only the UI your use case needs.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/audio -->

# Audio

Native audio playback that can provide media to a Video.js player

## Import

Import `Audio` from the audio preset:

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

## Anatomy

```tsx
<Audio>
  <source />
</Audio>
```

## Use with a player

Place `Audio` anywhere inside an `AudioPlayer`, or inside another Video.js `Player` configured for audio. It becomes that player’s media provider automatically. Outside a player, `Audio` behaves as a standalone native `<audio>`.

## Native behavior

Video.js does not replace the native audio API. Use `src` for one URL or add child [`<source>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source) when the browser should choose between candidates. See [Media sources](https://videojs.org/docs/framework/react/guides/media-sources) when you need an HLS, Mux, Spotify, or other playback adapter.

`Audio` forwards native attributes, event handlers, and children to the underlying `<audio>`. Its `ref` resolves to the `HTMLAudioElement`, and so does `mediaRef`. Adapter-backed components such as [HlsAudio](https://videojs.org/docs/framework/react/reference/components/hls-audio) and [SpotifyAudio](https://videojs.org/docs/framework/react/reference/components/spotify-audio) hand their playback adapter to `mediaRef` instead, so code that works with several media components can read the playback object from one prop.

See MDN for the complete [`<audio>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/audio), [`HTMLAudioElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement), and shared [`HTMLMediaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) APIs.

## Examples

### Basic Usage

This native audio element uses a child source and browser controls while providing media to the surrounding Video.js player.

**App.tsx**

```tsx
import { Container } from '@videojs/react';
import { Audio, AudioPlayer } from '@videojs/react/audio';

import './BasicUsage.css';

export default function BasicUsage() {
  return (
    <AudioPlayer>
      <Container className="react-audio-basic">
        <Audio className="react-audio-basic__media" controls preload="metadata">
          <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" />
        </Audio>
      </Container>
    </AudioPlayer>
  );
}
```

**App.css**

```css
.react-audio-basic {
  display: grid;
  width: 100%;
  padding: 24px;
  background: #e5e7eb;
  border-radius: 8px;
  place-items: center;
}

.react-audio-basic__media {
  width: 100%;
}
```

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/background-video -->

# BackgroundVideo

Decorative background video element with automatic muting and looping

Decorative background video for a source the browser can play natively. By default it’s muted, looped, and autoplaying.

`BackgroundVideo` renders a native `<video>`. Override the defaults with native React props such as `muted={false}`, `loop={false}`, or `autoPlay={false}`, and size the video with `className` or `style`. Its `ref` and `mediaRef` both resolve to that `HTMLVideoElement`.

An HLS URL only works where the browser has native HLS playback. See [Add a background video](https://videojs.org/docs/framework/react/guides/background-video) to choose a cross-browser HLS or Mux path and set up layout, poster, and decorative semantics.

## Import

```tsx
import { BackgroundVideo } from '@videojs/react/media/background-video';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { BackgroundVideo } from '@videojs/react/media/background-video';

export default function BasicUsage() {
  return (
    <div className="react-background-video-basic">
      <BackgroundVideo src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4" />
    </div>
  );
}
```

**App.css**

```css
.react-background-video-basic {
  position: relative;
  width: 100%;
  aspect-ratio: 16 / 9;
  overflow: hidden;
}

.react-background-video-basic > video {
  display: block;
  width: 100%;
  height: 100%;
  object-fit: cover;
}
```

## Styling

`BackgroundVideo` is the native `<video>` element, so size and position it with regular CSS. Use `object-fit` and `object-position` to control how the video fills its box.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/cloudflare-video -->

# CloudflareVideo

Video component that plays Cloudflare Stream videos through the Stream player

[Cloudflare Stream](https://developers.cloudflare.com/stream/) runs in an embedded player. Its own chrome stays hidden by default, so it drops into a [player skin](https://videojs.org/docs/framework/react/guides/skins) like any other media component; set `controls` to use Cloudflare’s UI instead.

## Import

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

```tsx
import { CloudflareVideo } from '@videojs/react/media/cloudflare-video';
```

## Load a source

`src` takes a raw 32-character video UID, any `cloudflarestream.com` or `videodelivery.net` URL, or a signed token. Watch, embed, iframe, manifest, and thumbnail URLs all carry the UID in the same position, and a signed token stands in for the UID wherever one appears.

```tsx
<CloudflareVideo src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" />
```

## Signed playback

For [signed URLs](https://developers.cloudflare.com/stream/viewing-videos/securing-your-stream/), pass the signed token wherever the UID would go: as the whole `src`, or inside a Stream URL. Keep your customer subdomain when your URLs name one. Cloudflare serves signed and access-controlled videos only from `customer-<code>.cloudflarestream.com`, so the element preserves that origin instead of collapsing it onto the shared host.

## Behavior

A few things work differently from a native `<video>` element, because the Stream embed doesn’t expose them:

- The embed owns text tracks: `textTracks` stays empty, and `engine.cloudflare.defaultTextTrack` picks the track to show.
- Picture-in-picture is unavailable, and the player reports it as unsupported.
- Fullscreen targets the iframe, so Cloudflare’s own chrome shows in fullscreen.
- `playsInline` has no effect: the Stream embed always plays inline.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CloudflareVideo } from '@videojs/react/media/cloudflare-video';

export default function BasicUsage() {
  return (
    <div className="cloudflare-video">
      <CloudflareVideo src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" controls />
    </div>
  );
}
```

**App.css**

```css
.cloudflare-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## 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?: CloudflareSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed parameters under `engine.cloudflare`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.cloudflare`

Pass [Stream player parameters](https://developers.cloudflare.com/stream/viewing-videos/using-the-stream-player/) under `source.engine.cloudflare`, spelled exactly as Cloudflare spells them, plus anything Cloudflare adds next. They’re serialized onto the embed URL untouched, and the embed reads them once, when its URL is built. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

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

```tsx
<CloudflareVideo
  source={{
    src: 'bfbd585059e33391d67b0f1d15fe6ea4',
    engine: { cloudflare: { primaryColor: '#f03e3e', startTime: '5m30s' } },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `ad-url` | `string \| undefined` | VAST tag to play as a pre-roll ad. Reported through the `stream-ad*` events. |
| `defaultTextTrack` | `string \| undefined` | BCP 47 language of the text track to show by default (`'en'`, `'de'`). |
| `letterboxColor` | `string \| undefined` | Any CSS color for the letterbox bars around a video that does not fill the player. |
| `primaryColor` | `string \| undefined` | Any CSS color for the progress bar and other player accents. |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Cloudflare player parameter. |
| `startTime` | `number \| string \| undefined` | Where playback starts, in seconds or as a time string (`'5m30s'`). |

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/cloudflare-video#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<CloudflareVideo ref={ref} />
```

#### `mediaRef`

Receives the `CloudflareAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { CloudflareAdapter } from '@videojs/cloudflare-video';

const mediaRef = useRef<CloudflareAdapter>(null);

<CloudflareVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/dash-video -->

# DashVideo

DASH video element powered by dash.js for adaptive bitrate streaming

> **Caution: Unstable API**
>
> This API works today, but its shape is still settling and may change in a minor release. The implementation underneath is production quality; what is not final is how you configure it from Video.js. Pin your version and check the changelog when you upgrade.

DASH video element powered by [dash.js](https://github.com/Dash-Industry-Forum/dash.js/) for MPEG-DASH adaptive bitrate streaming.

## Import

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

```tsx
import { DashVideo } from '@videojs/react/media/dash-video';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { DashVideo } from '@videojs/react/media/dash-video';

export default function BasicUsage() {
  return <DashVideo className="dash-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoPlay muted playsInline loop />;
}
```

**App.css**

```css
.dash-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `source` | `{ src?: string; engine?: DashEngineConfig } \| null` | `null` | Structured source: the MPD URL in `src`, plus dash.js settings in `engine.dashJs`. Replacing it re-derives `src`. Dash.js takes settings on a live player, so changing `engine.dashJs` re-applies them in place instead of recreating the engine. |
| `src` | `string` | `''` | |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<DashVideo ref={ref} />
```

#### `mediaRef`

Receives the `DashAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { DashAdapter } from '@videojs/dash-video';

const mediaRef = useRef<DashAdapter>(null);

<DashVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/hls-audio -->

# HlsAudio

Audio-only HLS element that plays the audio rendition of an HLS stream

Audio-only HLS element that plays just the audio rendition of an HLS stream — even when the source is a mixed audio/video manifest. Useful for audio podcast players, background audio, and bandwidth-constrained contexts where downloading video data would be wasted. For full audio/video HLS playback, see the [HLS video component](https://videojs.org/docs/framework/react/reference/components/hls-video).

## Import

```tsx
import { HlsAudio } from '@videojs/react/media/hls-audio';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { HlsAudio } from '@videojs/react/media/hls-audio';

export default function BasicUsage() {
  return <HlsAudio className="hls-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls />;
}
```

**App.css**

```css
.hls-audio {
  width: 100%;
  height: 54px;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<audio>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableRemotePlayback` | `boolean` | `false` | |
| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `''` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; type?: string; drm?: Partial<Record<string, DrmSystemConfig>> } \| null` | `null` | Structured source, the same shape the video flavor takes so one object serves either. `drm` is accepted and inert: this engine composes no EME. It is kept in the shape rather than removed so a source can be handed to both flavors — and because Mux encrypts video renditions and leaves audio clear, so a protected playback ID plays here regardless. |
| `src` | `string` | `''` | |

### Refs

#### `ref`

Forwards to the rendered `<audio>`, an [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLAudioElement>(null);

<HlsAudio ref={ref} />
```

#### `mediaRef`

Receives the `HlsAudioAdapter` that drives the `<audio>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { HlsAudioAdapter } from '@videojs/spf/hls-audio';

const mediaRef = useRef<HlsAudioAdapter>(null);

<HlsAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/hls-background-video -->

# HlsBackgroundVideo

HLS background video without controls, audio, captions, or adaptive quality

HlsBackgroundVideo plays an HLS source through the SPF background engine. It is fixed to muted, autoplaying, inline, looped playback and omits controls, audio, text, DRM, and adaptive rendition switching.

See [Add a background video](https://videojs.org/docs/framework/react/guides/background-video) for layout, poster, accessibility, and source-choice guidance.

## Import

```tsx
import { HlsBackgroundVideo } from '@videojs/react/media/hls-background-video';
```

## Source behavior

`src` takes a complete HLS manifest URL. The engine starts loading when it receives the URL and pins the largest rendition that fits the screen. The ladder may be video-only, but its video renditions must use fMP4/CMAF. This engine does not include MPEG-TS transmuxing or DRM playback.

```tsx
<HlsBackgroundVideo
  src="https://media.example.com/hero.m3u8"
  crossOrigin="anonymous"
  onError={handleError}
/>
```

There is no `source` object, `preload` mode, or opt-out for muted, autoplay, and loop. Assigning a new `src` restarts playback from scratch.

## API

| Member | Description |
| --- | --- |
| `src` | HLS manifest URL |
| `onError` | Fires on the rendered `<video>` when SPF reports a fatal source error |
| `ref` | Ref to the rendered native `<video>` element |
| `mediaRef` | Ref that receives the `HlsBackgroundVideoAdapter` driving the `<video>`, including its SPF `engine` |

`onError` receives an `error` event dispatched on the rendered `<video>`. The video’s own `error` can remain `null` because SPF, rather than the browser, rejected the source.

## Styling

The component renders a native `<video>`. Set its size, `object-fit`, and `object-position` through `className` or `style`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/hls-video -->

# HlsVideo

Lightweight HLS video element with minimal bundle size

The lightweight HLS video element, optimized for minimal bundle size. The [hls.js video component](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) is the larger, more compatible alternative.

## Import

```tsx
import { HlsVideo } from '@videojs/react/media/hls-video';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { HlsVideo } from '@videojs/react/media/hls-video';

export default function BasicUsage() {
  return <HlsVideo className="hls-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
}
```

**App.css**

```css
.hls-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableRemotePlayback` | `boolean` | `false` | |
| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `''` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; type?: string; drm?: Partial<Record<string, DrmSystemConfig>> } \| null` | `null` | Structured source: the manifest URL plus what a URL cannot carry, which today is the license servers for protected content. Setting it derives `src`. Assigning the same object back costs nothing — changing anything takes a new one. |
| `src` | `string` | `''` | |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | The source's stream type — `'live'`, `'on-demand'`, or `'unknown'` until a media playlist has been parsed. Setting a non-`'unknown'` value pins a user override (detection stops updating it); setting `'unknown'` reverts to the engine's detected value. |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<HlsVideo ref={ref} />
```

#### `mediaRef`

Receives the `HlsVideoAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { HlsVideoAdapter } from '@videojs/spf/hls-video';

const mediaRef = useRef<HlsVideoAdapter>(null);

<HlsVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/hlsjs-video -->

# HlsJsVideo

HLS video element powered by hls.js for adaptive bitrate streaming

HLS video element powered by [hls.js](https://github.com/video-dev/hls.js/) for adaptive bitrate streaming, with full feature support across every browser. It’s more compatible than the lightweight [HLS video component](https://videojs.org/docs/framework/react/reference/components/hls-video), which is smaller and covers most HLS playback. For browser-native playback, see the [native HLS video component](https://videojs.org/docs/framework/react/reference/components/native-hls-video).

## Import

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

```tsx
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

export default function BasicUsage() {
  return <HlsJsVideo className="hlsjs-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
}
```

**App.css**

```css
.hlsjs-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; type?: 'application/vnd.apple.mpegurl' \| 'video/mp4' \| string & {}; preferPlayback?: 'mse' \| 'native' \| string & {}; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`preferPlayback`, `engine`). Assigning it derives `src`. Sources are compared structurally, so reassigning an equivalent object is a no-op. Only a change to the engine options (or to the resolved content type) recreates the playback engine. |
| `src` | `string` | `''` | Media source URL. Assigning it replaces the identity half of `source` and leaves `type` and the engine options intact, so changing the URL never disturbs engine configuration. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Engine options

#### `source.engine.nativeHls`

When playback falls back to the browser’s own HLS, hls.js isn’t involved and its options don’t apply. This configures that path instead.

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<HlsJsVideo ref={ref} />
```

#### `mediaRef`

Receives the `HlsJsAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { HlsJsAdapter } from '@videojs/hlsjs-video';

const mediaRef = useRef<HlsJsAdapter>(null);

<HlsJsVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/mux-audio -->

# MuxAudio

Audio element for Mux-hosted HLS streams

Audio element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.

## Import

```bash
pnpm add @videojs/mux-audio
```

```tsx
import { MuxAudio } from '@videojs/react/media/mux-audio';
```

## Analytics and casting

The Mux audio component plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data) and [Google Cast](https://videojs.org/docs/framework/react/guides/casting) are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:

Install both extensions before using the example below:

```bash
pnpm add @videojs/mux-data @videojs/google-cast
```

```tsx
import { GoogleCast } from '@videojs/react/extensions/google-cast';
import { MuxAudio } from '@videojs/react/media/mux-audio';
import { MuxData } from '@videojs/react/extensions/mux-data';

<MuxAudio source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} />
<MuxData playerSoftwareName="mux-audio" />
<GoogleCast />
```

- [Mux Data — metadata, options, and configuration](https://videojs.org/docs/framework/react/guides/mux-data)
- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting)

## Examples

### Basic Usage

**App.tsx**

```tsx
import { MuxAudio } from '@videojs/react/media/mux-audio';

export default function BasicUsage() {
  return <MuxAudio className="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossOrigin="anonymous" controls />;
}
```

**App.css**

```css
.mux-audio {
  width: 100%;
  height: 54px;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<audio>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ type?: 'application/vnd.apple.mpegurl' \| 'video/mp4' \| string & {}; preferPlayback?: 'mse' \| 'native' \| string & {}; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null` | `null` | Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that *do* arrive adaptive selection reaches for. The two halves are independent. |
| `src` | `string` | `''` | Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`, with or without the `.m3u8` extension) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Engine options

#### `source.engine.nativeHls`

Options passed under `source.engine.nativeHls`.

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |

### Refs

#### `ref`

Forwards to the rendered `<audio>`, an [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLAudioElement>(null);

<MuxAudio ref={ref} />
```

#### `mediaRef`

Receives the `MuxAudioAdapter` that drives the `<audio>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { MuxAudioAdapter } from '@videojs/mux-audio';

const mediaRef = useRef<MuxAudioAdapter>(null);

<MuxAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/mux-background-video -->

# MuxBackgroundVideo

Mux-specific name for the HLS background video component

MuxBackgroundVideo is the Mux-specific name for [HlsBackgroundVideo](https://videojs.org/docs/framework/react/reference/components/hls-background-video). The two names use the same implementation and API.

Use this name when your source is a Mux HLS URL and the Mux identity makes the composition easier to read. See [Add a background video](https://videojs.org/docs/framework/react/guides/background-video) to compare the background-video options.

## Import

```tsx
import { MuxBackgroundVideo } from '@videojs/react/media/mux-background-video';
```

## Load a Mux source

Pass a complete Mux HLS URL through `src`. This component does not take a playback ID or structured `source` object. Use Mux delivery query parameters to limit which renditions Mux includes in the manifest:

```tsx
<MuxBackgroundVideo
  src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
  crossOrigin="anonymous"
/>
```

MuxBackgroundVideo does not create a poster or preview thumbnails, and it does not send analytics data. Keep the poster in your page and add analytics separately when you need them.

## API

The source, error, and fixed playback behavior are identical to [HlsBackgroundVideo](https://videojs.org/docs/framework/react/reference/components/hls-background-video).

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/mux-video -->

# MuxVideo

Video element for Mux-hosted HLS streams

Video element for playing Mux-hosted HLS streams. Built on hls.js with Mux-specific optimizations.

## Import

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

```tsx
import { MuxVideo } from '@videojs/react/media/mux-video';
```

## Load a source

The `source` param builds the URL for you from a playback ID, an optional custom domain, and `playback` params. Playback params are just camelCased [Mux playback query params](https://www.mux.com/docs/api-reference/stream/streaming/get-hls-manifest?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content); for example, `max_resolution` becomes `maxResolution`.

```tsx
<MuxVideo
  source={{ 
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    customDomain: 'media.example.com',
    playback: { maxResolution: '1080p' }
  }} 
/>
```

If for some reason you need a bit more control, you can use the `src` param with a plain ’ol URL, too:

```tsx
<MuxVideo
  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
/>
```

MuxVideo ignores the same source object when it is assigned again. A new object fires `sourcechange` even when its values are equal, although an equivalent playback source does not reload.

## Posters and storyboards

The Mux video component derives a poster image and a storyboard from the playback ID. `source.poster` and `source.storyboard` configure the generated URLs.

When the Mux video component is inside a player, it supplies the poster for the skin to display. Set `poster` on the player when you want to use your own image instead.

A generated poster becomes available after MuxVideo mounts. Pass `poster` to the player when the image must appear in server-rendered HTML.

The Mux video component injects the derived storyboard `<track>` automatically and removes it when the media detects a live stream. Configure the derived URLs through the source object:

```tsx
<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    poster: { time: 2, width: 1280 },
    storyboard: { format: 'webp' },
  }}
/>
```

The storyboard lives on a Mux domain, so the Mux video component has to be CORS-enabled for that cross-origin `<track>` to load at all. The [thumbnail component](https://videojs.org/docs/framework/react/reference/components/thumbnail) then fetches the sprite sheets its cues point at the same way:

```tsx
<MuxVideo
  source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }}
  crossOrigin="anonymous"
/>
```

## Signed playback

For [signed playback](https://www.mux.com/docs/guides/secure-video-playback?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content), put the playback token on `source.playback.token`. The token replaces every other playback param, so bake modifiers like resolution and time bounds into the token when you sign it.

Signed playback needs a separate token for each image URL. Put the thumbnail token (`aud: 't'`) at `source.poster.token` and the storyboard token (`aud: 's'`) at `source.storyboard.token`. If either token is missing or has the wrong audience, the Mux video component does not generate the corresponding URL.

```tsx
<MuxVideo
  source={{
    playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
    playback: { token: playbackToken },
    poster: { token: posterToken },
    storyboard: { token: storyboardToken },
  }}
/>
```

## Analytics and casting

The Mux video component plays Mux streams. It doesn’t monitor them or cast them — [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data) and [Google Cast](https://videojs.org/docs/framework/react/guides/casting) are separate extensions you add to the player alongside it. Mux Data needs no environment key here, since Mux attributes the views to the environment that owns the playback ID:

Install both extensions before using the example below:

```bash
pnpm add @videojs/mux-data @videojs/google-cast
```

```tsx
import { createPlayer } from '@videojs/react';
import { GoogleCast } from '@videojs/react/extensions/google-cast';
import { MuxData } from '@videojs/react/extensions/mux-data';
import { MuxVideo } from '@videojs/react/media/mux-video';
import { videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export function MuxPlayer() {
  return (
    <Player>
      <MuxVideo source={{ playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM' }} playsInline />
      <MuxData playerSoftwareName="mux-video" />
      <GoogleCast />
    </Player>
  );
}
```

- [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data): Metadata, options, and configuration
- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting): Receivers, load requests, and session state

## Examples

### Basic Usage

**App.tsx**

```tsx
import { MuxVideo } from '@videojs/react/media/mux-video';

export default function BasicUsage() {
  return (
    <MuxVideo
      className="mux-video"
      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
      autoPlay
      muted
      playsInline
      loop
      crossOrigin="anonymous"
    />
  );
}
```

**App.css**

```css
.mux-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ type?: 'application/vnd.apple.mpegurl' \| 'video/mp4' \| string & {}; preferPlayback?: 'mse' \| 'native' \| string & {}; maxAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; capRenditionToPlayerSize?: boolean; minAutoResolution?: '270p' \| '360p' \| '480p' \| '540p' \| '720p' \| '1080p' \| '1440p' \| '2160p'; engine?: HlsEngineConfig; src?: string; playbackId?: string; customDomain?: string; playback?: MuxPlaybackParams; poster?: MuxPosterParams; storyboard?: MuxStoryboardParams; drm?: MuxDrmParams } \| null` | `null` | Structured Mux source. Setting it derives `src` from the playback ID, custom domain, and `playback` params (appended as `snake_case` query params). A `playback.token` replaces all other params — signed URLs bake them into the token. Engine options live under `engine`. A `drm.token` fills in `drm` itself: Mux's FairPlay, Widevine, and PlayReady license servers for this playback ID, so protected media plays whichever path the browser takes. License servers named alongside the token win, key by key, for content Mux does not license. `playback.maxResolution` and `playback.minResolution` are server-side: they decide which renditions Mux puts in the manifest at all. The inherited `maxAutoResolution` and `minAutoResolution` only look like their pair — those are client-side and bound which of the renditions that *do* arrive adaptive selection reaches for. The two halves are independent. |
| `src` | `string` | `''` | Media source URL. Setting a Mux stream URL (`https://stream.mux.com/<playback-id>.m3u8?...`, with or without the `.m3u8` extension) extracts the playback ID and query params into `source`; other URLs are kept as a plain `source.src`. Only playback options carry over. Mux identity comes from the URL, and the signed `poster`, `storyboard`, and `drm` tokens are scoped to a playback ID, so carrying them onto a different source would build rejected URLs. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Engine options

#### `source.engine.nativeHls`

Options passed under `source.engine.nativeHls`.

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<MuxVideo ref={ref} />
```

#### `mediaRef`

Receives the `MuxVideoAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { MuxVideoAdapter } from '@videojs/mux-video';

const mediaRef = useRef<MuxVideoAdapter>(null);

<MuxVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/native-hls-video -->

# NativeHlsVideo

HLS video element using the browser's built-in HLS support

HLS video element that relies on the browser’s native HLS support. Works on Safari and other browsers with built-in HLS playback. For cross-browser HLS support, use the [hls.js video component](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) instead.

## Import

```tsx
import { NativeHlsVideo } from '@videojs/react/media/native-hls-video';
```

## Examples

### Basic Usage

**App.tsx**

```tsx
import { NativeHlsVideo } from '@videojs/react/media/native-hls-video';

export default function BasicUsage() {
  return <NativeHlsVideo className="native-hls-video" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />;
}
```

**App.css**

```css
.native-hls-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preload` | `MediaPreloadType` | `'metadata'` | Preload type (`'none'` / `'metadata'` / `'auto'`). |
| `source` | `{ src?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: NativeHlsEngineConfig } \| null` | `null` | Structured source: what to play (`src`) plus how to play it (`engine.nativeHls`). Assigning it derives `src`. Only a new URL reaches the element, so reassigning an equivalent source neither reloads nor disturbs key exchange. Use `src` or `load()` to reload what is already playing. Changing this source does not emit `sourcechange`. When the hls.js media component uses native HLS playback, it emits its own `sourcechange` and forwards the native playback events. |
| `src` | `string` | `''` | Media source URL. Assigning it replaces the identity half of `source` and leaves `engine` intact, so changing the URL never disturbs key exchange. Like the element's own `src`, assigning it always loads — including the URL already playing. |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Engine options

#### `source.engine.nativeHls`

This element hands playback to the browser, so there’s no JavaScript engine to configure. This carries the one thing native playback still needs from you. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

```tsx
<NativeHlsVideo
  source={{
    src: 'https://example.com/playlist.m3u8',
    engine: {
      nativeHls: {
        drmSystems: { 'com.apple.fps': { licenseUrl: 'https://example.com/license' } },
      },
    },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `drmSystems` | `Partial<Record<KeySystem, DrmSystemConfig>> \| undefined` | License servers for protected content, keyed by EME key system id. An escape hatch for licensing native playback differently from every other path: naming it replaces `source.drm` here, and nowhere else. |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<NativeHlsVideo ref={ref} />
```

#### `mediaRef`

Receives the `NativeHlsAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { NativeHlsAdapter } from '@videojs/native-hls-video';

const mediaRef = useRef<NativeHlsAdapter>(null);

<NativeHlsVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/shaka-video -->

# ShakaVideo

Video element powered by Shaka Player for DASH, HLS, and progressive playback with DRM

> **Caution: Unstable API**
>
> This API works today, but its shape is still settling and may change in a minor release. The implementation underneath is production quality; what is not final is how you configure it from Video.js. Pin your version and check the changelog when you upgrade.

Choose [Shaka Player](https://github.com/shaka-project/shaka-player) when one media component needs to play DASH, HLS, and progressive files, or when playback requires DRM.

## Import

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

```tsx
import { ShakaVideo } from '@videojs/react/media/shaka-video';
```

## Load a source

`src` takes a manifest URL. DASH, HLS, and progressive files all go through the same property, and Shaka picks the parser from the URL.

```tsx
<ShakaVideo src="https://example.com/manifest.mpd" />
```

When the URL carries no extension to go on, name the type with `source.type`. That’s what makes an extensionless manifest playable.

```tsx
<ShakaVideo source={{ src: 'https://example.com/manifest', type: 'application/dash+xml' }} />
```

## Protected content

`source.drm` names your license servers, keyed by [EME key system id](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/requestMediaKeySystemAccess). Name every system you hold a license server for: which one gets negotiated is the browser’s choice.

```tsx
<ShakaVideo
  source={{
    src: 'https://example.com/manifest.mpd',
    drm: {
      'com.widevine.alpha': { licenseUrl: 'https://example.com/widevine' },
      'com.apple.fps': {
        licenseUrl: 'https://example.com/fairplay',
        serverCertificateUrl: 'https://example.com/fairplay.cer',
      },
    },
  }}
/>
```

FairPlay needs a `serverCertificateUrl` unless its CDM is pre-provisioned; Widevine and PlayReady ignore it. `source.drm` takes the same shape as hls.js’s own `drmSystems`, so one object describes DRM for either engine.

For the parts of Shaka’s DRM configuration this doesn’t cover, configure Shaka directly. A `drm.servers` under `source.engine.shaka` replaces `source.drm` rather than merging with it.

## Behavior

- Adaptation stays within renditions no larger than the element rendering them, through Shaka’s `abr.restrictToElementSize`. Override it under `source.engine.shaka`.
- `preload="none"` defers the load until playback is asked for; `autoplay` or a `play()` counts as asking.
- `preload="metadata"` loads, then holds Shaka’s buffering goals down to a second until `preload` rises to `auto`.
- `streamType` is detected from the manifest, so a player skin renders live and on-demand content correctly without being told which it is.
- Changing `source.engine.shaka` reconfigures the running player in place instead of recreating it.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { ShakaVideo } from '@videojs/react/media/shaka-video';

export default function BasicUsage() {
  return <ShakaVideo className="shaka-video" src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoPlay muted playsInline loop />;
}
```

**App.css**

```css
.shaka-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## API Reference

### Props

Accepts the standard React props for a native `<video>`, plus these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `preload` | `'' \| 'none' \| 'metadata' \| 'auto'` | `'metadata'` | How much to fetch before playback is asked for, mirroring the media element's own `preload`. Shaka has no split between "know the source" and "buffer it", so this maps onto when and how `engine.load()` runs:<br>- `'auto'` — load immediately with the configured buffering goals.<br>- `'metadata'` — load immediately, holding buffering to about a segment; the configured goals come back on the first play intent.<br>- `'none'` / `''` — hold the load entirely until the first play intent. A play intent is a `play` event, a target that is already playing, or `autoplay` — which the spec lets override `preload` for good reason: with nothing fetched there is nothing whose readiness could ever fire it. Widening (`none` → `auto`) takes effect immediately; narrowing after a load began cannot un-fetch and leaves it alone. |
| `source` | `{ src?: string; type?: string; drm?: Partial<Record<KeySystem, DrmSystemConfig>>; engine?: ShakaEngineConfig } \| null` | `null` | Structured source: what to play (`src`, an optional `type`) plus how to play it (`drm`, `engine.shaka`). Replacing it re-derives `src`. Shaka takes configuration on a live player, so changing `engine.shaka` re-applies it in place instead of recreating the engine. |
| `src` | `string` | `''` | |
| `streamType` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | |

### Refs

#### `ref`

Forwards to the rendered `<video>`, an [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) with its complete native property and method API.

```tsx
const ref = useRef<HTMLVideoElement>(null);

<ShakaVideo ref={ref} />
```

#### `mediaRef`

Receives the `ShakaAdapter` that drives the `<video>`, the same object `useMedia()` returns inside a player. It forwards the native media methods, properties, and events, such as `play()` and `currentTime`, and exposes the playback engine through `engine`. It is set once the adapter has attached to the element and cleared when the element unmounts. For DOM-only APIs, use `ref`.

```tsx
import type { ShakaAdapter } from '@videojs/shaka-video';

const mediaRef = useRef<ShakaAdapter>(null);

<ShakaVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

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

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/spotify-audio -->

# SpotifyAudio

Audio component that plays Spotify tracks, episodes, playlists, and shows through the Spotify embed

The [Spotify embed](https://developer.spotify.com/documentation/embeds) accepts tracks, episodes, albums, playlists, shows, and artists. Podcast episodes play in full for signed-out listeners; music plays as a preview until the listener logs in to Spotify.

## Import

```bash
pnpm add @videojs/spotify-audio
```

```tsx
import { SpotifyAudio } from '@videojs/react/media/spotify-audio';
```

## Load a source

`src` takes an `open.spotify.com` URL for any embeddable entity, including the localized (`/intl-de/`) and already-embedded (`/embed/`) forms, or a `spotify:<type>:<id>` URI. A `t` parameter sets the start position in seconds.

```tsx
<SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
```

## Controls

Spotify’s own chrome is the only UI the embed offers, so `controls` decides whether the element is visible at all. With `controls`, it shows Spotify’s player. Without it, the element hides itself and plays as an invisible transport: a hidden iframe still loads and plays, so a [player skin](https://videojs.org/docs/framework/react/guides/skins)’s buttons drive playback while the embed takes no room on the page.

## Behavior

The Spotify embed exposes less than a native `<audio>` element:

- No volume and no mute: the embed takes neither command and reports neither value, so a player skin shows no volume controls at all.
- No playback rate and no text tracks.
- `loop` replays the entity from the top when it ends; without it, the embed continues into whatever Spotify queues next.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { SpotifyAudio } from '@videojs/react/media/spotify-audio';

export default function BasicUsage() {
  return (
    <div className="spotify-audio">
      <SpotifyAudio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls />
    </div>
  );
}
```

**App.css**

```css
.spotify-audio {
  width: 100%;
  height: 152px;
}
```

## API Reference

### Props

Accepts these Video.js-specific props:

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `controls` | `boolean` | `false` | |
| `loop` | `boolean` | `false` | |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `source` | `{ src?: string; engine?: SpotifySourceEngineConfig } \| null` | `null` | Spotify URL or URI in `src`, plus embed options under `engine.spotify`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.spotify`

Pass [Spotify embed options](https://developer.spotify.com/documentation/embeds) under `source.engine.spotify`, spelled exactly as Spotify spells them, plus anything Spotify adds next. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

```tsx
<SpotifyAudio
  source={{
    src: 'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5',
    engine: { spotify: { t: 90, theme: 0 } },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `preferVideo` | `boolean \| undefined` | Embed the video variant of an episode when it has one. Not a URL parameter: the video embed lives at its own path. |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Spotify embed parameter. |
| `t` | `number \| undefined` | Start position in seconds. |
| `theme` | `0 \| undefined` | `0` renders the embed in its dark theme. Defaults to the light theme. Spotify documents no other value, and the embed goes by whether the parameter is there, so leaving it out is the only way to ask for the default. |

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/spotify-audio#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<SpotifyAudio ref={ref} />
```

#### `mediaRef`

Receives the `SpotifyAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { SpotifyAdapter } from '@videojs/spotify-audio';

const mediaRef = useRef<SpotifyAdapter>(null);

<SpotifyAudio mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/tiktok-video -->

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

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/tiktok-video#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<TikTokVideo ref={ref} />
```

#### `mediaRef`

Receives the `TikTokAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { TikTokAdapter } from '@videojs/tiktok-video';

const mediaRef = useRef<TikTokAdapter>(null);

<TikTokVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/twitch-video -->

# TwitchVideo

Video component that plays Twitch videos and live channels through the Twitch embed player

The [Twitch embed player](https://dev.twitch.tv/docs/embed/video-and-clips/) handles both recorded videos and live channels. Its own chrome stays hidden by default, so it drops into a [player skin](https://videojs.org/docs/framework/react/guides/skins) like any other media component; set `controls` to use Twitch’s UI instead.

## Import

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

```tsx
import { TwitchVideo } from '@videojs/react/media/twitch-video';
```

## Load a source

`src` takes a video URL (`twitch.tv/videos/<id>`) or a channel URL (`twitch.tv/<channel>`), with or without the `www.` and `go.` hosts. A channel URL plays the channel’s live stream. Clips (`clips.twitch.tv`) are a different embed and aren’t supported.

```tsx
<TwitchVideo src="https://www.twitch.tv/videos/106400740" />
```

## Live channels

A channel embed behaves like a live media component:

- `duration` reports `Infinity` while the stream is live.
- Seeking is unavailable: the embed exposes no DVR window.
- The stream going away and coming back dispatch `offline` and `online` events.
- `loop` never repeats a channel; a live stream doesn’t end.

## Parent hostnames

Twitch checks the embedding page’s ancestors against a `parent` allowlist and won’t play unless the current page is on it. The element always includes your page’s own hostname, so a plain embed needs no setup. When your player is itself framed by other hostnames, name each of them under `engine.twitch.parent`:

```tsx
<TwitchVideo
  source={{
    src: 'https://www.twitch.tv/videos/106400740',
    engine: { twitch: { parent: ['embed.example.com'] } },
  }}
/>
```

## Behavior

- Volume and mute both work, like a native `<video>`.
- `playbackRate` is reported but never applied: the embed has no rate command.
- `loop` restarts a finished video from the top; the embed has no loop parameter.
- `controls` is read when the embed is built; changing it later doesn’t take effect, since rebuilding the iframe would lose the playback session.
- Fullscreen targets the iframe, so Twitch’s own chrome shows in fullscreen.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { TwitchVideo } from '@videojs/react/media/twitch-video';

export default function BasicUsage() {
  return (
    <div className="twitch-video">
      <TwitchVideo src="https://www.twitch.tv/videos/106400740" controls />
    </div>
  );
}
```

**App.css**

```css
.twitch-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## 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?: TwitchSourceEngineConfig } \| null` | `null` | Twitch VOD or channel URL in `src`, plus embed parameters under `engine.twitch`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.twitch`

Pass [Twitch embed parameters](https://dev.twitch.tv/docs/embed/video-and-clips/) under `source.engine.twitch`, spelled exactly as Twitch spells them, plus anything Twitch adds next. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

`controls`, `autoplay`, and `muted` come from the props of the same name, and the video or channel comes from `src`, so none of those have an `engine.twitch` spelling.

| Option | Type | Description |
| --- | --- | --- |
| `collection` | `string \| undefined` | Collection to play through, starting from the video named by `src`. |
| `parent` | `string \| readonly string[] \| undefined` | Every hostname the embed may be framed by. Twitch checks the frame's ancestors against it and refuses to play when the current page is missing, which is why the page's own hostname is always included on top of this. |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Twitch embed parameter, so it never reaches the URL: the React player applies it to the iframe it renders, and the HTML player reads its own `referrerpolicy` attribute instead. |
| `time` | `string \| undefined` | Start position, spelled the way Twitch spells timestamps: `1h30m10s`. |

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/twitch-video#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<TwitchVideo ref={ref} />
```

#### `mediaRef`

Receives the `TwitchAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { TwitchAdapter } from '@videojs/twitch-video';

const mediaRef = useRef<TwitchAdapter>(null);

<TwitchVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/video -->

# Video

Native video playback that can provide media to a Video.js player

## Import

Import `Video` from the video preset:

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

## Anatomy

```tsx
<Video>
  <source />
  <track />
</Video>
```

## Use with a player

Place `Video` anywhere inside a `VideoPlayer`, or inside another Video.js `Player` configured for video. It becomes that player’s media provider automatically. Outside a player, `Video` behaves as a standalone native `<video>`.

## Native behavior

Video.js does not replace the native video API. Use `src` for one URL or add child [`<source>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/source) when the browser should choose between candidates. See [Media sources](https://videojs.org/docs/framework/react/guides/media-sources) when you need an HLS, DASH, Mux, or other playback adapter.

Add native [`<track>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/track) for captions, subtitles, chapters, descriptions, or metadata.

`Video` forwards native attributes, event handlers, and children to the underlying `<video>`. Its `ref` resolves to the `HTMLVideoElement`, and so does `mediaRef`. Adapter-backed components such as [HlsJsVideo](https://videojs.org/docs/framework/react/reference/components/hlsjs-video) and [YouTubeVideo](https://videojs.org/docs/framework/react/reference/components/youtube-video) hand their playback adapter to `mediaRef` instead, so code that works with several media components can read the playback object from one prop.

See MDN for the complete [`<video>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/video), [`HTMLVideoElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement), and shared [`HTMLMediaElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement) APIs.

## Examples

### Basic Usage

This native video uses a child source, captions track, and browser controls while also providing media to the surrounding Video.js player.

**App.tsx**

```tsx
import { Container } from '@videojs/react';
import { Video, VideoPlayer } from '@videojs/react/video';

import './BasicUsage.css';

export default function BasicUsage() {
  return (
    <VideoPlayer>
      <Container className="react-video-basic">
        <Video className="react-video-basic__media" controls playsInline preload="metadata">
          <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" type="video/mp4" />
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
        </Video>
      </Container>
    </VideoPlayer>
  );
}
```

**App.css**

```css
.react-video-basic {
  width: 100%;
  overflow: hidden;
  background: black;
  border-radius: 8px;
}

.react-video-basic__media {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/vimeo-video -->

# VimeoVideo

Video component that plays Vimeo videos and live events through the Vimeo player

Of the embed-backed media components, the [Vimeo player SDK](https://developer.vimeo.com/player/sdk) comes closest to a native `<video>`: volume, mute, playback rate, seeking, looping, and picture-in-picture all work, and the embed pushes real events instead of being polled. Vimeo’s own chrome stays hidden by default, so it drops into a [player skin](https://videojs.org/docs/framework/react/guides/skins) like any other media component; set `controls` to use Vimeo’s UI instead.

## Import

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

```tsx
import { VimeoVideo } from '@videojs/react/media/vimeo-video';
```

## Load a source

`src` takes a numeric video id or a Vimeo URL. Watch (`vimeo.com/<id>`), embed (`player.vimeo.com/video/<id>`), and event (`vimeo.com/event/<id>`) URLs all work.

```tsx
<VimeoVideo src="https://vimeo.com/76979871" />
```

Collection URLs aren’t supported: channels, showcases, albums, groups, on-demand pages, and user-scoped paths carry no id the player can load. Link to a specific video instead. `#t=` fragments are ignored as well; use `engine.vimeo.start_time` to start partway in.

## Unlisted videos

An unlisted video needs the hash Vimeo issues alongside its id. Pass it the way Vimeo writes it, either as a trailing path segment or as an `h` parameter:

```plaintext
https://vimeo.com/76979871/abc123def
https://vimeo.com/76979871?h=abc123def
```

Both reach the embed as its `h` parameter. When a URL carries the hash in both places, the `h` parameter wins.

## Live events

A `vimeo.com/event/<id>` URL plays that event through Vimeo’s event embed, and its unlisted hash becomes a path segment rather than a parameter. The media reports no stream type or live window, so a player skin renders it with the same controls as an on-demand video rather than a live UI.

## Behavior

- Fullscreen goes through the Vimeo player, so Vimeo’s own fullscreen chrome appears and the player reports the state back.
- Captions round-trip by name only: the embed’s track list appears in `textTracks` and selecting one enables it, but no cues cross over. Vimeo draws captions inside the iframe.
- `poster` has no effect. The embed shows its own thumbnail, which `engine.vimeo.thumbnail_id` picks.
- `playbackRate` is limited to Vimeo’s supported range, 0.5 through 2.
- `playsInline` and `preload` are read when the embed URL is built, so changing them later doesn’t take effect.
- The video’s Vimeo title arrives as content data, so a player skin can show it without fetching anything yourself.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { VimeoVideo } from '@videojs/react/media/vimeo-video';

export default function BasicUsage() {
  return (
    <div className="vimeo-video">
      <VimeoVideo src="https://vimeo.com/76979871" controls />
    </div>
  );
}
```

**App.css**

```css
.vimeo-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## 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?: VimeoSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed options under `engine.vimeo`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.vimeo`

Pass [Vimeo embed parameters](https://developer.vimeo.com/player/sdk/embed) under `source.engine.vimeo`, spelled exactly as Vimeo spells them. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

These options are typed from Vimeo’s own SDK, so your editor completes every parameter and rejects one Vimeo doesn’t have. That also means the list covers Vimeo’s oEmbed API alongside the player: `id` and `url` both override the video `src` names, and `width`, `height`, `maxwidth`, `maxheight`, and `responsive` size an oEmbed response rather than this element. Pass the video through `src`, and size the element with CSS.

`autoplay`, `controls`, `loop`, `muted`, `playsinline`, and `preload` come from the props of the same name. Setting them here overrides the prop, which is worth knowing when a value seems to be ignored. The element also sends `transparent: false`, where Vimeo’s default is `true`.

```tsx
<VimeoVideo
  source={{
    src: 'https://vimeo.com/76979871',
    engine: { vimeo: { color: 'f03e3e', start_time: 30, speed: true } },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a Vimeo embed parameter. |

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/vimeo-video#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<VimeoVideo ref={ref} />
```

#### `mediaRef`

Receives the `VimeoAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { VimeoAdapter } from '@videojs/vimeo-video';

const mediaRef = useRef<VimeoAdapter>(null);

<VimeoVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/wistia-video -->

# WistiaVideo

Video component that plays Wistia-hosted videos through Wistia's web component

`WistiaVideo` adapts Wistia’s own `<wistia-player>` web component to the Video.js media contract. Wistia’s chrome stays hidden by default so a Video.js player skin can control playback; set `controls` to use Wistia’s UI.

## Import

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

```tsx
import { WistiaVideo } from '@videojs/react/media/wistia-video';
```

## Load a source

`src` accepts a Wistia media URL or hashed media ID. A `wtime` query parameter sets the initial playback position.

```tsx
<WistiaVideo src="https://example.wistia.com/medias/abcde12345?wtime=30" />
```

## Wistia options

Pass Wistia player options through `source`. `mediaId` selects the media; other properties such as `playerColor`, `qualityMin`, and `roundedPlayer` are forwarded to Wistia.

```tsx
<WistiaVideo
  source={{
    mediaId: 'abcde12345',
    playerColor: '54bbff',
    qualityMin: 540,
  }}
/>
```

## Behavior

- Every Wistia media is treated as on-demand video. Live windows, remote playback, and picture-in-picture are unavailable.
- `controls` switches Wistia’s own chrome and pointer interaction on. Without it, pointer events pass through to the Video.js skin.
- `loop`, `muted`, `autoplay`, `poster`, and `preload` are translated to Wistia’s option names. Wistia always plays inline, so `playsInline` has no additional effect.
- Changing the media ID loads a new Wistia player. Changing only player options keeps the current player and playback session.

`ref` and `mediaRef` both resolve to the rendered `<wistia-player>`. Video.js adapts that element in place, so it is the playback object as well: call `play()` or set `currentTime` on it directly.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { WistiaVideo } from '@videojs/react/media/wistia-video';

export default function BasicUsage() {
  return <WistiaVideo className="wistia-video" src="https://wesleyluyten.wistia.com/medias/oifkgmxnkb" controls />;
}
```

**App.css**

```css
.wistia-video {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/youtube-video -->

# YouTubeVideo

Video component that plays YouTube videos and playlists through the YouTube IFrame player

The [YouTube IFrame player](https://developers.google.com/youtube/iframe_api_reference) keeps its own chrome hidden by default, so it drops into a [player skin](https://videojs.org/docs/framework/react/guides/skins) like any other media component; set `controls` to use YouTube’s UI instead.

## Import

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

```tsx
import { YouTubeVideo } from '@videojs/react/media/youtube-video';
```

## Load a source

`src` takes a YouTube URL or a raw 11-character video id. Watch, share (`youtu.be`), embed, Shorts, live, and privacy-enhanced (`youtube-nocookie.com`) URLs all work. Playlist URLs load through their `list` parameter, and a `t` parameter sets the start position.

```tsx
<YouTubeVideo src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" />
```

## Behavior

A few things work differently from a native `<video>` element, because the IFrame API doesn’t expose them:

- `loop` restarts playback when the video ends; the IFrame API has no single-video loop.
- Fullscreen targets the iframe, so YouTube’s own chrome shows in fullscreen.
- Picture-in-picture is unavailable, and the player reports it as unsupported.
- Caption tracks appear in `textTracks` once playback starts; YouTube reports no caption metadata before then.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { YouTubeVideo } from '@videojs/react/media/youtube-video';

export default function BasicUsage() {
  return (
    <div className="youtube-video">
      <YouTubeVideo src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" controls />
    </div>
  );
}
```

**App.css**

```css
.youtube-video {
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

## 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?: YouTubeSourceEngineConfig } \| null` | `null` | YouTube URL or id in `src`, plus player parameters under `engine.youtube`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |

### Engine options

#### `source.engine.youtube`

Pass [YouTube player parameters](https://developers.google.com/youtube/player_parameters) under `source.engine.youtube`, spelled exactly as YouTube spells them. They’re serialized onto the embed URL untouched, and the embed reads them once, when its URL is built. [Media Sources](https://videojs.org/docs/framework/react/guides/media-sources) covers how engine options fit into a structured source.

`autoplay`, `controls`, and `playsinline` come from the props of the same name, so they have no `engine.youtube` spelling. Parameters YouTube has deprecated are absent as well: `modestbranding`, `showinfo`, `autohide`, `theme`, and `listType: 'search'`. Anything YouTube adds next passes through the same way.

```tsx
<YouTubeVideo
  source={{
    src: 'https://www.youtube.com/watch?v=aqz-KE-bpKQ',
    engine: { youtube: { hl: 'de', cc_load_policy: 1 } },
  }}
/>
```

| Option | Type | Description |
| --- | --- | --- |
| `cc_lang_pref` | `string \| undefined` | ISO 639-1 language to display captions in. Pair with `cc_load_policy`. |
| `cc_load_policy` | `1 \| undefined` | Show closed captions by default, even if the viewer has turned them off. |
| `color` | `'red' \| 'white' \| undefined` | Progress-bar highlight color. Defaults to `'red'`. |
| `disablekb` | `0 \| 1 \| undefined` | Stop responding to keyboard controls. Defaults to `0`. |
| `enablejsapi` | `0 \| 1 \| undefined` | Allow the player to be driven through the IFrame Player API. Defaults to `0`. |
| `end` | `number \| undefined` | Stop playback this many seconds from the start of the video. |
| `fs` | `0 \| 1 \| undefined` | Display the fullscreen button. Defaults to `1`. |
| `hl` | `string \| undefined` | Player interface language: an ISO 639-1 code or full locale (`fr`, `fr-ca`). |
| `iv_load_policy` | `1 \| 3 \| undefined` | Show video annotations (`1`) or hide them (`3`). Defaults to `1`. |
| `list` | `string \| undefined` | Playlist id (prefixed with `PL`) or channel name, depending on `listType`. |
| `listType` | `'playlist' \| 'user_uploads' \| undefined` | What `list` refers to. |
| `loop` | `0 \| 1 \| undefined` | Repeat playback. Looping a single video also needs `playlist` set to the same id. |
| `origin` | `string \| undefined` | Embedding domain. Set it whenever `enablejsapi` is `1`. |
| `playlist` | `string \| undefined` | Comma-separated video ids to play after the one named by the URL path. |
| `referrerPolicy` | `ReferrerPolicy \| undefined` | `referrerpolicy` for the embed iframe. Not a YouTube player parameter. |
| `rel` | `0 \| 1 \| undefined` | Draw related videos from the same channel (`0`) or anywhere (`1`). Defaults to `1`. |
| `start` | `number \| undefined` | Begin playback this many seconds from the start of the video. |
| `widget_referrer` | `string \| undefined` | Embedding URL reported to YouTube Analytics for widget-hosted players. |

### Refs

#### `ref`

Forwards to the rendered `<iframe>`, an [HTMLIFrameElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLIFrameElement). The iframe cannot play or seek; use [`mediaRef`](https://videojs.org/docs/framework/react/reference/components/youtube-video#media-ref) for playback.

```tsx
const ref = useRef<HTMLIFrameElement>(null);

<YouTubeVideo ref={ref} />
```

#### `mediaRef`

Receives the `YouTubeAdapter` that drives the embed, which exposes media methods and properties such as `play()` and `currentTime`. It is set once the adapter has attached to the iframe, so its `target` is already that iframe, and it is cleared when the iframe unmounts.

```tsx
import type { YouTubeAdapter } from '@videojs/youtube-video';

const mediaRef = useRef<YouTubeAdapter>(null);

<YouTubeVideo mediaRef={mediaRef} />

// In an event handler
mediaRef.current?.play();
```

### Events

Handle standard media events with React event props such as `onPlay` and `onTimeUpdate`. The adapter dispatches them, not the iframe. For events without a React prop, call `addEventListener` on the adapter from `mediaRef`.

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/google-cast -->

# GoogleCast

Options for the Google Cast extension that configures the receiver and load request

Adds the [Google Cast extension](https://videojs.org/docs/framework/react/guides/architecture) to the player. It renders nothing — place it anywhere inside the player, and pair it with a [CastButton](https://videojs.org/docs/framework/react/reference/components/cast-button). It follows whatever media the player attaches, a plain `<video>` included. See [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting) for the complete setup.

## Import

```bash
pnpm add @videojs/react @videojs/google-cast
```

```tsx
import { GoogleCast } from '@videojs/react/extensions/google-cast';
```

## Anatomy

```tsx
<GoogleCast />
```

## Options

| Prop | Type | Description |
| --- | --- | --- |
| `receiver` | `string` | Cast receiver application ID. Defaults to Google’s Default Media Receiver (`CC1AD845`) |
| `src` | `string` | Source URL loaded on the receiver. Defaults to the source the browser is playing. Required for YouTube and Vimeo embeds |
| `contentType` | `string` | MIME type of the Cast source. When unset, the receiver infers it from the URL |
| `streamType` | `'on-demand' \| 'live'` | Stream type reported to the receiver. Falls back to the player’s stream type |
| `customData` | `object` | Custom data sent to the receiver with each load request |

When the Cast `src` is an HLS playlist, Video.js detects the segment format and sets the receiver’s `hlsSegmentFormat` and `hlsVideoSegmentFormat` load-request fields. The Default Media Receiver plays HLS natively, so no extra receiver setup is needed.

## See also

- [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting): Add remote playback to a player
- [CastButton component reference](https://videojs.org/docs/framework/react/reference/components/cast-button)
- [Remote Playback feature reference](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback)

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/mux-data -->

# MuxData

Options for the Mux Data extension that monitors playback quality

Adds the [Mux Data](https://data.mux.com/?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) [extension](https://videojs.org/docs/framework/react/guides/architecture) to the player. It renders nothing — place it anywhere inside the player, and it follows whatever media the player attaches. See [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data) for how monitoring works.

## Import

```bash
pnpm add @videojs/react @videojs/mux-data
```

```tsx
import { MuxData } from '@videojs/react/extensions/mux-data';
```

## Anatomy

```tsx
<MuxData />
```

## Options

| Prop | Type | Description |
| --- | --- | --- |
| `envKey` | `string` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
| `metadata` | `object` | Mux Data metadata for the view |
| `playerSoftwareName` | `string` | Player name reported to Mux Data |
| `playerSoftwareVersion` | `string` | Player version reported to Mux Data. Defaults to the Video.js version |
| `playerInitTime` | `number` | Epoch milliseconds the player was initialized. Defaults to when the player was created |
| `beaconCollectionDomain` | `string` | Custom domain the beacons are sent to |
| `disableCookies` | `boolean` | Stops the SDK from setting cookies |
| `debug` | `boolean` | Turns on SDK debug logging |
| `MuxDataSdk` | `object` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |

Changing `MuxDataSdk`, `beaconCollectionDomain`, `debug`, or `disableCookies` restarts monitoring, which ends the current view and starts a new one. The rest update the view in place.

## See also

- [Mux Data](https://videojs.org/docs/framework/react/guides/mux-data): How monitoring works
- [Mux video reference](https://videojs.org/docs/framework/react/reference/components/mux-video)
- [Mux audio reference](https://videojs.org/docs/framework/react/reference/components/mux-audio)

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/play-button -->

# PlayButton

Accessible play/pause button with keyboard support and customizable rendering

## Import

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

## Anatomy

```tsx
<PlayButton />
```

## Behavior

The play button is a three-state button: **play**, **pause**, and **replay**. When media reaches the end (`ended` state), clicking restarts playback from the beginning.

## Styling

Style with the `[data-paused]` and `[data-ended]` attributes to show/hide play/pause/replay icons based on state. For example:

React renders a `<button>` element. Add a `className` to style it:

```css
/* Paused (but not ended) */
.play-button[data-paused]:not([data-ended]) .play-icon { display: inline; }

/* Playing */
.play-button:not([data-paused]) .pause-icon { display: inline; }

/* Ended */
.play-button[data-ended] .replay-icon { display: inline; }
```

After first play, the `data-started` attribute is added and remains present until a new source is loaded. Use this to hide the play button when media hasn’t started yet:

```css
/* Hide play button before first play */
.play-button:not([data-started]) .play-icon { display: none; }
```

## Accessibility

Renders a `<button>` element with an automatic `aria-label` that updates based on state: “Play”, “Pause”, or “Replay”. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'buttons.play', text: 'Play video' }`. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, PlayButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline />
        <PlayButton
          className="media-play-button"
          render={(props, state) => (
            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
          )}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-play-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: PlayButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `paused` | `boolean` | Whether playback is paused. |
| `ended` | `boolean` | Whether playback has reached the end. |
| `started` | `boolean` | Whether playback has started (played or seeked). |
| `label` | `{ key: string; text: string } \| string` | |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-paused` | Present when the media is paused. |
| `data-ended` | Present when the media has ended. |
| `data-started` | Present when playback has started. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/mute-button -->

# MuteButton

Accessible mute/unmute button with keyboard support and volume state reflection

## Import

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

## Anatomy

```tsx
<MuteButton />
```

## Behavior

Toggles mute on and off, and exposes a derived `volumeLevel` based on the current volume and mute state.

Mute availability is separate from volume-level availability because some media can accept a mute command without supporting volume changes.

When mute is unavailable or unsupported, the component returns `null`. Toggling is also ignored while mute is unavailable.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-muted` | Present / absent | Present when the media is muted |
| `data-volume-level` | `"off"` \| `"low"` \| `"medium"` \| `"high"` | Current volume level |
| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether the media can be muted |
| `data-hidden` | Present / absent | Present on the HTML element while mute is unavailable or unsupported |

Style the button based on muted state:

React renders a `<button>` element. Add a `className` to style it:

```css
.mute-button[data-muted] .icon-muted { display: inline; }
.mute-button:not([data-muted]) .icon-unmuted { display: inline; }
```

Use `data-volume-level` for multi-level icon switching:

```css
.mute-button[data-volume-level="off"] .icon-off { display: inline; }
.mute-button[data-volume-level="low"] .icon-low { display: inline; }
.mute-button[data-volume-level="medium"] .icon-medium { display: inline; }
.mute-button[data-volume-level="high"] .icon-high { display: inline; }
```

Unavailable and unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`: “Unmute” when muted, “Mute” when unmuted. Override with the `label` prop. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, MuteButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <MuteButton
          className="media-mute-button"
          render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-mute-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

### Volume Levels

**App.tsx**

```tsx
import { Container, createPlayer, MuteButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function VolumeLevels() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <MuteButton
          className="media-mute-button"
          render={(props, state) => (
            <button {...props}>
              {state.volumeLevel === 'off'
                ? 'Off'
                : state.volumeLevel === 'low'
                  ? 'Low'
                  : state.volumeLevel === 'medium'
                    ? 'Medium'
                    : 'High'}
            </button>
          )}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-mute-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: MuteButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `muted` | `boolean` | Whether audio is muted. |
| `label` | `{ key: string; text: string } \| string` | |
| `volumeLevel` | `'off' \| 'low' \| 'medium' \| 'high'` | Derived volume level:<br>- `off`: muted or volume is 0<br>- `low`: volume < 0.5<br>- `medium`: volume < 0.75<br>- `high`: volume >= 0.75 |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether the media can be muted at all. |
| `hidden` | `boolean` | Whether the button is hidden because the media has no mute to toggle. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-muted` | — | Present when the media is muted. |
| `data-volume-level` | `'off' \| 'low' \| 'medium' \| 'high'` | Indicates the volume level. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates mute availability (`available`, `unavailable`, `unsupported`). |
| `data-hidden` | — | Present when the button is hidden because the media has no mute to toggle. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/seek-button -->

# SeekButton

Accessible seek button for skipping forward or backward by a configurable number of seconds

## Import

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

## Anatomy

```tsx
<SeekButton />
```

## Behavior

Seeks media by a configurable number of `seconds` (default 30). Positive values seek forward, negative values seek backward. The seek is clamped to media bounds (0 to duration).

## Accessibility

Renders a `<button>` with an automatic `aria-label` describing the action, e.g. “Seek forward 30 seconds” or “Seek backward 10 seconds”. Override with the `label` prop. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, SeekButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <div className="buttons">
          <SeekButton
            seconds={-5}
            className="media-seek-button"
            render={(props, state) => (
              <button {...props}>
                {state.direction === 'backward' ? '\u23EA' : '\u23E9'} {5}s
              </button>
            )}
          />
          <SeekButton
            seconds={10}
            className="media-seek-button"
            render={(props, state) => (
              <button {...props}>
                {10}s {state.direction === 'forward' ? '\u23E9' : '\u23EA'}
              </button>
            )}
          />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.buttons {
  position: absolute;
  bottom: 10px;
  left: 10px;
  display: flex;
  gap: 8px;
}

.media-seek-button {
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  white-space: nowrap;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: SeekButtonState) => Text \| string)` | `''` | Custom label for the button. |
| `seconds` | `number` | `30` | Seconds to seek. Positive = forward, negative = backward. Default `30`. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `seeking` | `boolean` | Whether a seek is in progress. |
| `direction` | `'forward' \| 'backward'` | Whether the button seeks forward or backward. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-seeking` | — | Present when a seek is in progress. |
| `data-direction` | `'forward' \| 'backward'` | Indicates the seek direction: `"forward"` or `"backward"`. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/fullscreen-button -->

# FullscreenButton

Accessible fullscreen toggle button with keyboard support and state reflection

## Import

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

## Anatomy

```tsx
<FullscreenButton />
```

## Behavior

Toggles fullscreen mode. The button derives two state hooks from `availability`:

- **`disabled`** (`true` until fullscreen is available, or when the `disabled` prop is set) — sets `aria-disabled="true"` and `data-disabled`. A prop-disabled, available button stays focusable but does not activate.
- **`hidden`** (`true` while fullscreen is `"unavailable"` or `"unsupported"`) — the component returns `null`.

## Styling

You can style the button based on fullscreen state:

React renders a `<button>` element. Add a `className` to style it:

```css
/* In fullscreen */
.fullscreen-button[data-fullscreen] {
  background: red;
}

/* Non-interactive (disabled prop) */
.fullscreen-button[data-disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

The button remains hidden until fullscreen is available.

The component returns `null`. No extra CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`: “Enter fullscreen” or “Exit fullscreen”. Override with the `label` prop. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, FullscreenButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <FullscreenButton
          className="media-fullscreen-button"
          render={(props, state) => <button {...props}>{state.fullscreen ? 'Exit Fullscreen' : 'Fullscreen'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-fullscreen-button {
  position: absolute;
  right: 10px;
  bottom: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: FullscreenButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `fullscreen` | `boolean` | Whether fullscreen mode is currently active. |
| `availability` | `MediaFeatureAvailability` | Whether fullscreen can be requested on this platform. |
| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
| `hidden` | `boolean` | Whether the button is hidden until fullscreen is available. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-fullscreen` | — | Present when fullscreen mode is active. |
| `data-availability` | `MediaFeatureAvailability` | Indicates fullscreen availability (`available`, `unavailable`, `unsupported`). |
| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
| `data-hidden` | — | Present when the button is hidden because fullscreen is not available. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/pip-button -->

# PiPButton

Accessible picture-in-picture toggle button with keyboard support and state reflection

## Import

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

## Anatomy

```tsx
<PiPButton />
```

## Behavior

Toggles picture-in-picture (PiP) mode. The button derives two state hooks from `availability`:

- **`disabled`** (`true` until PiP is available, or when the `disabled` prop is set) — sets `aria-disabled="true"` and `data-disabled`. A prop-disabled, available button stays focusable but does not activate.
- **`hidden`** (`true` while PiP is `"unavailable"` or `"unsupported"`) — the component returns `null`.

## Styling

You can style the button based on PiP state:

React renders a `<button>` element. Add a `className` to style it:

```css
/* In PiP mode */
.pip-button[data-pip] {
  background: red;
}

/* Non-interactive (disabled prop) */
.pip-button[data-disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

The button remains hidden until picture-in-picture is available.

The component returns `null`. No extra CSS is required.

## Accessibility

The default English `aria-label` is “Enter picture-in-picture”, or “Exit picture-in-picture” while picture-in-picture is active. The `label` prop overrides it. The button supports keyboard activation with Enter or Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, PiPButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <PiPButton
          className="media-pip-button"
          render={(props, state) => <button {...props}>{state.pip ? 'Exit PiP' : 'Enter PiP'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-pip-button {
  position: absolute;
  right: 10px;
  bottom: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: PiPButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `pip` | `boolean` | Whether picture-in-picture mode is currently active. |
| `availability` | `MediaFeatureAvailability` | Whether picture-in-picture can be requested on this platform. |
| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
| `hidden` | `boolean` | Whether the button is hidden until picture-in-picture is available. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-pip` | — | Present when picture-in-picture mode is active. |
| `data-availability` | `MediaFeatureAvailability` | Indicates picture-in-picture availability (`available`, `unavailable`, `unsupported`). |
| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
| `data-hidden` | — | Present when the button is hidden because picture-in-picture is not available. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/captions-button -->

# CaptionsButton

Accessible captions toggle button with availability detection and state reflection

## Import

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

## Anatomy

```tsx
<CaptionsButton />
```

## Behavior

Toggles captions and subtitles on and off. The button checks the media’s text track list for tracks with `kind="captions"` or `kind="subtitles"`.

When none are present, the component returns `null`.

An explicitly disabled button with caption tracks stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not toggle captions.

When `menuTrigger` is enabled and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly. `menuTrigger` is enabled automatically when a `CaptionsButton` is rendered inside `Menu.Trigger`.

## Styling

Style the button based on active state:

React renders a `<button>` element. Add a `className` to style it:

```css
.captions-button[data-active] .icon-on { display: inline; }
.captions-button:not([data-active]) .icon-off { display: inline; }
```

Style an explicitly disabled, available button:

```css
.captions-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}
```

The button hides automatically when no caption tracks are available. No availability selector or extra hiding CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`: “Disable captions” when active, “Enable captions” when inactive. Override with the `label` prop. Keyboard activation: Enter / Space.

In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CaptionsButton, Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
        </Video>
        <CaptionsButton
          className="media-captions-button"
          render={(props, state) => (
            <button {...props}>{state.subtitlesShowing ? 'Captions Off' : 'Captions On'}</button>
          )}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-captions-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: CaptionsButtonState) => Text \| string)` | `''` | Custom label for the button. |
| `menuTrigger` | `boolean` | `false` | When true with multiple tracks, pointer activation opens a menu instead of toggling. React sets this automatically inside `Menu.Trigger`. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
| `label` | `{ key: string; text: string } \| string` | |
| `availability` | `'available' \| 'unavailable'` | Whether caption/subtitle tracks are present. |
| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
| `hidden` | `boolean` | Whether the button is hidden because no caption tracks are present. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-active` | — | Present when captions are enabled. |
| `data-availability` | `'available' \| 'unavailable'` | Indicates captions availability (`available` or `unavailable`). |
| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
| `data-hidden` | — | Present when the button is hidden because no caption tracks are present. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/playback-rate-button -->

# PlaybackRateButton

A button that cycles through playback speed rates

## Import

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

## Anatomy

```tsx
<PlaybackRateButton />
```

## Behavior

Cycles through playback rates on click. The default rate list is `[0.2, 0.5, 0.7, 1, 1.2, 1.5, 1.7, 2]`. After the last rate, it wraps back to the first. If the current rate isn’t in the list (e.g., set programmatically), the button jumps to the next rate greater than the current one.

When `menuTrigger` is enabled, activation opens the linked playback-rate menu instead of cycling through rates. Use this mode when the button is the trigger for a `Menu` that contains playback-rate options.

## Styling

Display the current rate using the `data-rate` attribute:

Use the `render` prop for rate display:

```tsx
<PlaybackRateButton
  render={(props, state) => <button {...props}>{state.rate}&times;</button>}
/>
```

## Accessibility

Renders a `<button>` with an automatic `aria-label` of `"Playback rate {rate}"` (e.g., `"Playback rate 1.5"`). Override with the `label` prop. Keyboard activation: Enter / Space.

In menu-trigger mode, the button behaves as a menu trigger and reflects menu state through the trigger attributes.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, PlaybackRateButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <PlaybackRateButton
          className="media-playback-rate-button"
          render={(props, state) => <button {...props}>{Math.round(state.rate * 10) / 10}&times;</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-playback-rate-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: PlaybackRateButtonState) => Text \| string)` | `''` | Custom label for the button. |
| `menuTrigger` | `boolean` | `false` | When true, pointer activation opens a menu instead of cycling. React sets this automatically inside `Menu.Trigger`. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type |
| --- | --- |
| `label` | `{ key: string; text: string } \| string` |
| `rate` | `number` |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-rate` | `number` | Current playback rate. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/live-button -->

# LiveButton

Accessible live indicator button that seeks to the live edge when pressed

## Import

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

## Anatomy

```tsx
<LiveButton />
```

## Behavior

The live button indicates whether playback is at the live edge and acts as a “go to live” control. While playback is behind the edge, clicking seeks to the live edge — the end of the last `seekable` range. At the edge the button goes inactive (`aria-disabled`) and clicking is a no-op.

The button is also disabled whenever it has no live edge to seek to: the media is not live, the `seekable` ranges are still empty (before metadata loads, for example), or the last range ends at `Infinity`. It reports `disabled` in its state, sets `data-disabled`, and ignores activation until a seek target exists. Passing `disabled` forces the same state.

The button combines three player features: [live](https://videojs.org/docs/framework/react/reference/api/feature-live) for `liveEdgeStart` and `targetLiveWindow`, [time](https://videojs.org/docs/framework/react/reference/api/feature-time) for `currentTime` and the `seek()` action, and [buffer](https://videojs.org/docs/framework/react/reference/api/feature-buffer) for `seekable`. All three are included in the `liveVideoFeatures` and `liveAudioFeatures` presets, and the packaged live skins include the button.

Media counts as live while `targetLiveWindow` is not `NaN`. That value is how far behind the live edge viewers can seek: `0` means the stream is watchable only at the edge, and `Infinity` means the stream keeps its recording seekable so viewers can rewind and catch up, like a DVR. For on-demand media the button reports neither `live` nor `liveEdge` and stays inert.

The live edge is not a single instant: it begins 5 seconds before `liveEdgeStart`, the position the media reports live playback starting at, so playback that drifts slightly behind still counts as live. When the media does not report `liveEdgeStart`, the edge is the trailing 10 seconds of the seekable window instead.

Without children, the button renders the translated “Live” badge text.

See [Play live streams](https://videojs.org/docs/framework/react/guides/live-streams) for how live state flows through the player.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-live` | Present / absent | Present when the stream is live (or DVR) |
| `data-live-edge` | Present / absent | Present when playback is at the live edge |
| `data-disabled` | Present / absent | Present when the button is non-interactive (mirrors `aria-disabled`) |

Use `data-live-edge` to color the button red at the edge and gray behind it, and `data-disabled` to fade it while no live-edge target is available:

React renders a `<button>` element with the same data attributes. Add a `className` and use it as the selector:

```css
.live-button { color: gray; }
.live-button[data-live-edge] { color: red; }
.live-button[data-disabled] { opacity: 0.5; }
```

## Accessibility

Renders a `<button>` with an automatic `aria-label` that updates based on state: “Playing live” at the live edge, “Seek to live edge” while behind it. Override with the `label` prop, which accepts a text descriptor, literal string, or function returning either. A text descriptor contains an opaque translation key and English fallback, for example `{ key: 'live.playing', text: 'Playing live' }`. When the button is disabled — explicitly, or because no live-edge seek target is available yet — or playback is at the live edge, `aria-disabled="true"` is set and activation is ignored. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

The demo plays a continuously running live stream. Seek backward to move behind the live edge, then press the Live button to jump back to it.

**App.tsx**

```tsx
import { Container, createPlayer, LiveButton, SeekButton } from '@videojs/react';
import { liveVideoFeatures } from '@videojs/react/live-video';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';

const { Player } = createPlayer({ features: liveVideoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-live-button-basic">
        <HlsJsVideo src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" autoPlay muted playsInline />
        <div className="react-live-button-basic__buttons">
          <SeekButton seconds={-30} className="react-live-button-basic__seek">
            {'⏪'} 30s
          </SeekButton>
          <LiveButton className="react-live-button-basic__live">
            <span className="react-live-button-basic__dot" />
            Live
          </LiveButton>
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-live-button-basic {
  position: relative;
}

.react-live-button-basic video {
  width: 100%;
}

.react-live-button-basic__buttons {
  position: absolute;
  bottom: 10px;
  left: 10px;
  display: flex;
  gap: 8px;
}

.react-live-button-basic__seek,
.react-live-button-basic__live {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  white-space: nowrap;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.react-live-button-basic__live[data-live-edge] {
  cursor: default;
}

.react-live-button-basic__dot {
  width: 8px;
  height: 8px;
  background: gray;
  border-radius: 50%;
}

.react-live-button-basic__live[data-live-edge] .react-live-button-basic__dot {
  background: red;
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: LiveButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `live` | `boolean` | Whether the stream is live (or DVR). |
| `liveEdge` | `boolean` | Whether playback is at the live edge. |
| `disabled` | `boolean` | Whether seeking to the live edge is temporarily unavailable. |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-live` | Present when the stream is live (or DVR). |
| `data-live-edge` | Present when playback is at the live edge. |
| `data-disabled` | Present when the button is non-interactive (mirrors `aria-disabled`). |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/airplay-button -->

# AirPlayButton

Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state

## Import

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

## Anatomy

```tsx
<AirPlayButton />
```

## Behavior

Opens the WebKit AirPlay playback target picker and reflects session state. AirPlay is a WebKit-only feature, so the button reports `availability: "unsupported"` outside Safari (macOS and iOS). On supported platforms availability flips to `"available"` once Safari discovers at least one AirPlay receiver on the local network, and `"unavailable"` otherwise.

The button is hidden until `availability` is `"available"`: the component returns `null`.

An explicitly disabled, otherwise available button stays visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker.

The component consumes the unified [`remotePlayback`](https://videojs.org/docs/framework/react/reference/api/feature-remote-playback) store feature alongside `CastButton`: both buttons drive their state from the same feature, but each only surfaces on its supported platform (WebKit for AirPlay, Chromium for Cast).

WebKit does not expose a `"connecting"` intermediate state — the `state` slice flips directly between `"disconnected"` and `"connected"` when the AirPlay session changes. When connected, the picker itself acts as the disconnect UI.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-airplay-state` | `"disconnected"` \| `"connecting"` \| `"connected"` | Current AirPlay session state |
| `data-availability` | `"available"` \| `"unavailable"` \| `"unsupported"` | Whether AirPlay is reachable on the current platform |
| `data-disabled` | Present / absent | Present when the button is non-interactive |
| `data-hidden` | Present / absent | Present on the HTML element while AirPlay is unavailable or unsupported |

Use `data-airplay-state` to swap icons or labels based on the session state:

React renders a `<button>` element. Add a `className` and use it as the selector:

```css
/* AirPlay active */
.airplay-button[data-airplay-state="connected"] {
  color: var(--accent);
}
```

Use `data-disabled` to style an explicitly disabled, available button:

```css
.airplay-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}
```

Unavailable and unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`: “Start AirPlay” when disconnected, “Stop AirPlay” when connected. (The component also supports a `"Connecting"` label, but WebKit AirPlay never emits a `connecting` state, so that label is unreachable in practice.) Override with the `label` prop — either a string or a function that receives the current state. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { AirPlayButton, Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <AirPlayButton
          className="media-airplay-button"
          render={(props, state) => (
            <button {...props}>{state.state === 'connected' ? 'Stop AirPlay' : 'Start AirPlay'}</button>
          )}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-airplay-button {
  position: absolute;
  right: 10px;
  bottom: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

/* Explicitly disabled while AirPlay is available. */
.media-airplay-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
  filter: grayscale(1);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: AirPlayButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `state` | `'disconnected' \| 'connecting' \| 'connected'` | Current AirPlay connection state. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether AirPlay is available on the active platform and media. |
| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
| `hidden` | `boolean` | Whether the button is hidden until AirPlay is available. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-airplay-state` | `'disconnected' \| 'connecting' \| 'connected'` | Current AirPlay connection state. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether AirPlay is available on the active platform and media. |
| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
| `data-hidden` | — | Present when the button is hidden because AirPlay is unavailable. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/cast-button -->

# CastButton

Accessible Cast toggle button with state reflection and keyboard support

## Import

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

## Anatomy

```tsx
<CastButton />
```

## Behavior

Toggles a Google Cast session. Clicking the button while `disconnected` opens the Cast device picker; clicking while `connected` ends the session.

The button derives its presentation from `availability`:

- **`"unsupported"`** — the component returns `null`.
- **`"unavailable"`** — the button remains visible and focusable with `aria-disabled="true"` and `data-disabled`, but does not open the picker. This lets a tooltip explain that no Cast device is reachable.
- **`"available"`** — the button is fully interactive unless the `disabled` prop is set.

Configurable Cast sessions come from the [Google Cast extension](https://videojs.org/docs/framework/react/reference/components/google-cast). Add it to the player next to your media component; without it the button drives the browser’s native Remote Playback API instead, which offers no receiver or load-request configuration. See [Cast to AirPlay and Chromecast](https://videojs.org/docs/framework/react/guides/casting) for the complete setup.

## Styling

Style based on cast and disabled state:

React renders a `<button>` element. Add a `className` to style it:

```css
/* During an active session */
.cast-button[data-cast-state="connected"] {
  color: blue;
}

/* Cast is supported, but no device is reachable */
.cast-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
}
```

Unsupported buttons are hidden automatically. No availability selector or extra hiding CSS is required.

## Accessibility

Renders a `<button>` with an automatic `aria-label`:

| Cast state | Default label |
| --- | --- |
| `'disconnected'` | “Start casting” |
| `'connecting'` | “Connecting” |
| `'connected'` | “Stop casting” |

Override with the `label` prop. Keyboard activation: Enter / Space.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { CastButton, Container, createPlayer } from '@videojs/react';
import { GoogleCast } from '@videojs/react/extensions/google-cast';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoPlay muted playsInline loop />
        <GoogleCast />
        <CastButton
          className="media-cast-button"
          render={(props, state) => (
            <button {...props}>{state.connection === 'connected' ? 'Stop casting' : 'Start casting'}</button>
          )}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-cast-button {
  position: absolute;
  right: 10px;
  bottom: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-cast-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
  filter: grayscale(1);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the button is disabled. |
| `label` | `{ key: string; text: string } \| string \| ((state: CastButtonState) => Text \| string)` | `''` | Custom label for the button. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `connection` | `'disconnected' \| 'connecting' \| 'connected'` | Current cast connection state (`disconnected`, `connecting`, or `connected`). |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether casting is `available` (a device is reachable), `unavailable` (no device), or `unsupported`. |
| `disabled` | `boolean` | Non-interactive but still focusable (mirrors `aria-disabled`). |
| `hidden` | `boolean` | Whether the button is hidden because the feature is unsupported. |

### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-cast-state` | `'disconnected' \| 'connecting' \| 'connected'` | Current remote playback connection state. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether remote playback can be requested on this platform. |
| `data-disabled` | — | Present when the button is non-interactive (mirrors `aria-disabled`). |
| `data-hidden` | — | Present when the button is hidden because the feature is unsupported. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/slider -->

# Slider

A composable slider component with track, fill, thumb, preview, and value parts

## Import

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

## Anatomy

```tsx
<Slider.Root>
  <Slider.Track>
    <Slider.Fill />
  </Slider.Track>
  <Slider.Thumb />
  <Slider.Preview>
    <Slider.Thumbnail.Root>
      <Slider.Thumbnail.Image />
    </Slider.Thumbnail.Root>
    <Slider.Value type="pointer" />
  </Slider.Preview>
</Slider.Root>
```

## Behavior

The base slider provides a generic range input. It manages value, pointer tracking, and drag interactions. The [time slider](https://videojs.org/docs/framework/react/reference/components/time-slider) and [volume slider](https://videojs.org/docs/framework/react/reference/components/volume-slider) add media-specific bindings. The time slider also provides parts for rendering chapter ranges and the chapter at the current interaction position.

`Slider.Thumbnail.Root` supplies the pointer value to the thumbnail. Render `Slider.Thumbnail.Image` inside it for the controlled image; other children can provide loading indicators or overlays.

The slider supports vertical orientation via the `orientation` prop (defaults to `"horizontal"`).

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/react/reference/components/slider#root-css-custom-properties) to position fill, thumb, and preview elements:

React renders standard DOM elements. Add a `className` to style them:

```css
.slider-fill {
  width: var(--media-slider-fill);
}

.slider-thumb {
  left: var(--media-slider-fill);
}
```

Style based on [interaction state](https://videojs.org/docs/framework/react/reference/components/slider#root-data-attributes):

```css
.slider[data-interactive] .slider-track {
  height: 6px;
}
.slider[data-pointing] .slider-preview {
  opacity: 1;
}
```

## Accessibility

Renders with `role="slider"` and automatic ARIA attributes (`aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-valuetext`). Override the label with the `label` prop. Keyboard controls:

- Arrow Left / Arrow Right: step by `step` increment
- Page Up / Page Down: step by `largeStep` increment
- Home: jump to minimum
- End: jump to maximum

## Examples

### Basic

A slider with track, fill, and thumb.

**App.tsx**

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

export default function BasicUsage() {
  const [value, setValue] = useState(50);

  return (
    <div className="demo">
      <Slider.Root className="media-slider" value={value} onValueChange={setValue}>
        <Slider.Track className="media-slider-track">
          <Slider.Fill className="media-slider-fill" />
        </Slider.Track>
        <Slider.Thumb className="media-slider-thumb" />
      </Slider.Root>
    </div>
  );
}
```

**App.css**

```css
.demo {
  display: flex;
  align-items: center;
  padding: 24px;
  background: #1a1a1a;
}

.media-slider {
  position: relative;
  display: flex;
  align-items: center;
  width: 100%;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-slider[data-dragging] .media-slider-thumb {
  transform: translateX(-50%) scale(1.1);
}
```

### With Preview

A slider with a pointer-tracking preview that displays the value at the current pointer position.

**App.tsx**

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

export default function WithPreview() {
  const [value, setValue] = useState(50);

  return (
    <div className="demo">
      <Slider.Root className="media-slider" value={value} onValueChange={setValue}>
        <Slider.Track className="media-slider-track">
          <Slider.Fill className="media-slider-fill" />
        </Slider.Track>
        <Slider.Thumb className="media-slider-thumb" />
        <Slider.Preview className="preview">
          <Slider.Value type="pointer" className="media-slider-value" />
        </Slider.Preview>
      </Slider.Root>
    </div>
  );
}
```

**App.css**

```css
.demo {
  display: flex;
  align-items: center;
  padding: 40px 24px;
  background: #1a1a1a;
}

.media-slider {
  position: relative;
  display: flex;
  align-items: center;
  width: 100%;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-slider[data-dragging] .media-slider-thumb {
  transform: translateX(-50%) scale(1.1);
}

.preview {
  position: absolute;
  bottom: 100%;
  margin-bottom: 6px;
  pointer-events: none;
  opacity: 0;
  transition: opacity 150ms ease;
}

.media-slider[data-pointing] .preview {
  opacity: 1;
}

.media-slider-value {
  padding: 2px 6px;
  font-size: 12px;
  color: white;
  white-space: nowrap;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 4px;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether the slider is non-interactive. |
| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
| `largeStep` | `number` | `10` | Large step increment (Page Up/Down keys). |
| `max` | `number` | `100` | Maximum value of the slider range. |
| `min` | `number` | `0` | Minimum value of the slider range. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of slider movement. |
| `step` | `number` | `1` | Step increment for value changes (arrow keys). |
| `thumbAlignment` | `'center' \| 'edge'` | `'center'` | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
| `value` | `number` | `0` | Current slider value. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `value` | `number` | Current slider value in the min–max range. |
| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
| `dragging` | `boolean` | Whether the user is actively dragging. |
| `pointing` | `boolean` | Whether the pointer is over the slider. |
| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
| `disabled` | `boolean` | Whether the slider is non-interactive. |
| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-slider-fill` | Fill level percentage (0–100). |
| `--media-slider-pointer` | Pointer position percentage (0–100). |
| `--media-slider-buffer` | Buffer level percentage (0–100). |

### Buffer

Displays the buffered range on the slider track.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Fill

Displays the filled portion from start to the current value.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Track

Contains the slider's visual track and interactive hit zone.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays a formatted text representation of the slider value. Renders an `<output>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `format` | `((value: number) => string)` | — | Custom formatter for the displayed value. Overrides the root's `formatValue`. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Thumbnail.Root

Resolves, sizes, and clips the thumbnail at the slider pointer.

Render `Slider.Thumbnail.Image` inside it for the controlled image. Other children can provide loading indicators, overlays, or temporary presentation layers.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `thumbnails` | `ThumbnailImage[]` | — | Pre-parsed thumbnail images — bypasses the automatic `<track>` detection. |

### Thumbnail.Image

Displays the image selected and measured by `Thumbnail.Root`.

Renders an `img`, so native image attributes and the `render` escape hatch remain available without replacing the root that owns thumbnail state.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `crossOrigin` | `ThumbnailCrossOrigin` | — | CORS setting for the selected image. Leave unset to follow the media component, or pass `null` to opt out. |
| `fetchPriority` | `ThumbnailFetchPriority` | — | Image fetch priority hint. |
| `loading` | `ThumbnailLoading` | — | Image loading strategy. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/time-slider -->

# TimeSlider

A slider component for seeking through media playback time

## Import

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

## Anatomy

```tsx
<TimeSlider.Root>
  <TimeSlider.Track>
    <TimeSlider.Buffer />
    <TimeSlider.Fill />
  </TimeSlider.Track>
  <TimeSlider.Thumb />
  <TimeSlider.Preview>
    <TimeSlider.ChapterTitle />
    <TimeSlider.Value type="pointer" />
  </TimeSlider.Preview>
</TimeSlider.Root>
```

Add `Chapters` to divide the slider track into sections. Each cue in the default `kind="chapters"` text track marks a chapter. Without chapter cues, one section covers the full slider.

```tsx
<TimeSlider.Chapters
  renderChapter={(props, state) => (
    <div {...props}>
      <TimeSlider.Track>
        <TimeSlider.Buffer />
        <TimeSlider.Fill />
      </TimeSlider.Track>
    </div>
  )}
/>
```

`renderChapter` receives the attributes, styles, and state for each normalized chapter range. When no chapter cues are available, it renders once as a full-width, cue-less range. Spread the attributes on the chapter’s root element: they carry the slider’s data attributes, the chapter’s `data-active` and `data-highlighted` attributes, and a `style` that sets its `--media-slider-chapter-*` custom properties.

The state is a `TimeSliderChapterState`, exported from `@videojs/react`:

| Field | Type | Description |
| --- | --- | --- |
| `cue` | `MediaTextCue \| null` | The chapter cue, or `null` for a gap range. |
| `key` | `string` | Stable identity of the range. |
| `index` | `number` | Position of the range, from `0`. |
| `start`, `end` | `number` | Range bounds, in seconds. |
| `startPercent`, `endPercent` | `` `${number}%` `` | Range bounds as a percentage of the slider. |
| `width`, `height` | `` `${number}%` \| undefined `` | Range size along the slider’s orientation; the other is `undefined`. |
| `orientation` | `'horizontal' \| 'vertical'` | The slider’s orientation. |
| `highlight` | `boolean \| undefined` | Whether the range can be highlighted: `true` for a chapter, `false` for a gap range. |
| `fillPercent` | `number` | Fill within the range, from 0 to 100. |
| `bufferPercent` | `number` | Buffer within the range, from 0 to 100. |
| `active` | `boolean` | Playback is within the range. |
| `pointing` | `boolean` | The pointer is within the range. |
| `dragging` | `boolean` | The drag value is within the range. |
| `highlighted` | `boolean` | Pointer interaction highlights the range. |
| `interactive` | `boolean` | The range is the current interaction target. |

## Behavior

Displays and controls the current playback position. Dragging the slider seeks the media. The fill level reflects `currentTime / duration` as a percentage, and the buffer level shows how much media has been buffered.

Value changes during drag are throttled via the `changeThrottle` prop (default 100ms) using a leading+trailing throttle to keep the UI responsive without overwhelming the media element.

Chapter cues are normalized into contiguous ranges. Any uncovered time becomes a gap range, so track geometry always spans the full duration. With no usable chapter cues, one gap range spans the entire slider. Gap ranges receive the same geometry styles but cannot be highlighted and have no chapter title.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/react/reference/components/time-slider#root-css-custom-properties) to style the fill, pointer, and buffer levels:

React renders a `<div>` element. Add a `className` to style it:

```css
.time-slider::before {
  width: var(--media-slider-fill);
}
```

Use `data-seeking` to style during active seek operations:

```css
.time-slider[data-seeking] {
  opacity: 0.8;
}
```

Each rendered chapter receives `data-active` while playback is inside it and `data-highlighted` while the pointer is inside an authored chapter. Its geometry and local progress are exposed through:

- `--media-slider-chapter-start`
- `--media-slider-chapter-end`
- `--media-slider-chapter-width`
- `--media-slider-chapter-fill`
- `--media-slider-chapter-buffer`

The generated fill and buffer parts also inherit the slider-level `--media-slider-fill` and `--media-slider-buffer` values. This allows every chapter to render full-width progress planes and use its chapter bounds as a clip, keeping progress transitions continuous across segments.

## Accessibility

Renders with `role="slider"` and an automatic `aria-label` that resolves to “Seek” from the active locale. Override with the `label` prop. Keyboard controls:

- Arrow Left / Arrow Right: step by `step` increment
- Page Up / Page Down: step by `largeStep` increment
- Home: seek to start
- End: seek to end

`ChapterTitle` follows the pointer during pointer interaction. While the slider has keyboard focus, it follows the current playback position and announces chapter changes.

## Examples

Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, buffer indicator, draggable thumb, and a tooltip that shows the pointed-at time.

**App.tsx**

```tsx
import { Container, createPlayer, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function WithParts() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <TimeSlider.Root className="media-time-slider">
          <TimeSlider.Track className="media-slider-track">
            <TimeSlider.Buffer className="media-slider-buffer" />
            <TimeSlider.Fill className="media-slider-fill" />
          </TimeSlider.Track>
          <TimeSlider.Thumb className="media-slider-thumb" />
          <TimeSlider.Value type="pointer" className="media-slider-value" />
        </TimeSlider.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-time-slider {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  display: flex;
  align-items: center;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-buffer {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-buffer);
  height: 100%;
  background: rgba(255, 255, 255, 0.4);
  border-radius: 9999px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-time-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
  transform: translateX(-50%) scale(1.1);
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
}

.media-slider-value {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  padding: 2px 6px;
  margin-bottom: 6px;
  font-size: 12px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 4px;
  opacity: 0;
  transform: translateX(-50%);
  transition: opacity 150ms ease;
}

.media-time-slider[data-pointing] .media-slider-value {
  opacity: 1;
}
```

### With chapters

Add a default chapters track, then provide the markup used for each chapter. The deliberate one-minute gap in this example remains visible as an unlabelled, non-highlightable segment.

**App.tsx**

```tsx
import { Container, createPlayer, TimeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function WithChapters() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop crossOrigin="anonymous">
          <track kind="chapters" src="/docs/demos/time-slider/chapters.vtt" srcLang="en" default />
        </Video>
        <TimeSlider.Root className="media-time-slider">
          <TimeSlider.Chapters
            className="media-slider-chapters"
            renderChapter={(props) => (
              <div {...props} className="media-slider-chapter">
                <TimeSlider.Track className="media-slider-track">
                  <TimeSlider.Buffer className="media-slider-buffer" />
                  <TimeSlider.Fill className="media-slider-fill" />
                </TimeSlider.Track>
              </div>
            )}
          />
          <TimeSlider.Thumb className="media-slider-thumb" />
          <TimeSlider.Preview className="media-slider-preview">
            <TimeSlider.ChapterTitle className="media-slider-chapter-title" />
            <TimeSlider.Value type="pointer" />
          </TimeSlider.Preview>
        </TimeSlider.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-time-slider {
  position: absolute;
  right: 12px;
  bottom: 8px;
  left: 12px;
  display: flex;
  align-items: center;
  height: 20px;
  color: white;
  cursor: pointer;
}

.media-slider-chapters {
  position: relative;
  width: 100%;
  height: 100%;
}

.media-slider-chapter {
  position: absolute;
  inset: 0;
  display: flex;
  align-items: center;
  clip-path: inset(0 calc(100% - var(--media-slider-chapter-end)) 0 var(--media-slider-chapter-start));
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  overflow: hidden;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
  transition: height 150ms ease;
}

.media-slider-chapter .media-slider-track {
  clip-path: inset(
    0 calc(100% - var(--media-slider-chapter-end) + 2px) 0 calc(var(--media-slider-chapter-start) + 2px) round 9999px
  );
}

.media-slider-chapter[data-highlighted] .media-slider-track {
  height: 7px;
}

.media-slider-buffer,
.media-slider-fill {
  position: absolute;
  inset-block: 0;
  left: 0;
  border-radius: inherit;
  transition: width 200ms linear;
}

.media-slider-buffer {
  width: var(--media-slider-buffer);
  background: rgb(255 255 255 / 30%);
}

.media-slider-fill {
  width: var(--media-slider-fill);
  background: white;
}

.media-time-slider[data-dragging] .media-slider-fill {
  width: var(--media-slider-pointer);
  transition-duration: 0ms;
}

.media-slider-thumb {
  position: absolute;
  top: 50%;
  left: var(--media-slider-fill);
  width: 12px;
  height: 12px;
  background: white;
  border-radius: 50%;
  translate: -50% -50%;
}

.media-time-slider[data-dragging] .media-slider-thumb {
  left: var(--media-slider-pointer);
}

.media-slider-preview {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  display: flex;
  gap: 6px;
  padding: 3px 7px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgb(0 0 0 / 80%);
  border-radius: 4px;
  opacity: 0;
  translate: -50% -4px;
}

.media-time-slider[data-pointing] .media-slider-preview,
.media-time-slider[data-interactive]:not([data-pointing]) .media-slider-preview {
  opacity: 1;
}

.media-slider-chapter-title:empty {
  display: none;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `changeThrottle` | `number` | `100` | Leading+trailing throttle (ms) for `onValueChange` during drag. |
| `disabled` | `boolean` | — | Whether the slider is non-interactive. |
| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
| `largeStep` | `number` | — | Large step increment (Page Up/Down keys). |
| `max` | `number` | — | |
| `min` | `number` | — | |
| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
| `pauseOnDrag` | `boolean` | `false` | When true, pause playback while the user is dragging the thumb, resuming on release if it was playing before. |
| `step` | `number` | — | Step increment for value changes (arrow keys). |
| `thumbAlignment` | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
| `value` | `number` | — | |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `value` | `number` | Current slider value in the min–max range. |
| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
| `dragging` | `boolean` | Whether the user is actively dragging. |
| `pointing` | `boolean` | Whether the pointer is over the slider. |
| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
| `disabled` | `boolean` | Whether the slider is non-interactive. |
| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |
| `currentTime` | `number` | Current playback position in seconds. |
| `duration` | `number` | Total duration in seconds (0 if unknown). |
| `seeking` | `boolean` | Whether a seek operation is in progress. |
| `bufferPercent` | `number` | Buffered amount as a percentage of duration (0–100). |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-seeking` | Present when a seek operation is in progress. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-slider-fill` | Fill level percentage (0–100), representing current playback position. |
| `--media-slider-pointer` | Pointer position percentage (0–100), tracking the cursor along the slider. |
| `--media-slider-buffer` | Buffer level percentage (0–100), indicating how much media has been buffered. |

### ChapterTitle

Displays the chapter title at the current pointer or keyboard position.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TimeSliderChapterTitleState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TimeSliderChapterTitleState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TimeSliderChapterTitleState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Chapters

Renders normalized chapter ranges across the full slider, including one full range when chapter cues are absent.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TimeSliderChaptersState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TimeSliderChaptersState) => ReactElement \| null)` | — | Render prop for custom element. |
| `renderChapter` | `((props: Omit<HTMLProps<HTMLElement>, 'ref'>, state: TimeSliderChapterState) => ReactElement)` | — | Render one consumer-owned subtree for every normalized chapter range. |
| `style` | `CSSProperties \| ((state: TimeSliderChaptersState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Buffer

Displays the buffered range on the slider track.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Fill

Displays the filled portion from start to the current value.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Track

Contains the slider's visual track and interactive hit zone.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays a formatted text representation of the slider value. Renders an `<output>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `format` | `((value: number) => string)` | — | Custom formatter for the displayed value. Overrides the root's `formatValue`. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/volume-slider -->

# VolumeSlider

A slider component for controlling media playback volume

## Import

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

## Anatomy

```tsx
<VolumeSlider.Root>
  <VolumeSlider.Track>
    <VolumeSlider.Fill />
  </VolumeSlider.Track>
  <VolumeSlider.Thumb />
  <VolumeSlider.Preview>
    <VolumeSlider.Value type="pointer" />
  </VolumeSlider.Preview>
</VolumeSlider.Root>
```

## Behavior

Controls the media volume level. The slider maps its 0–100 internal range to the media’s 0–1 volume scale. When the media is muted, the fill level drops to 0 regardless of the stored volume value.

When `volumeAvailability` is not `"available"`, the component returns `null`. This is independent of `mutedAvailability`, which controls whether the mute button is shown.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/react/reference/components/volume-slider#root-css-custom-properties) to style the fill and pointer levels:

React renders a `<div>` element. Add a `className` to style it:

```css
.volume-slider::before {
  width: var(--media-slider-fill);
}
```

## Accessibility

Renders with `role="slider"` and an automatic `aria-label` that resolves to “Volume” from the active locale. Override with the `label` prop. Keyboard controls:

- Arrow Left / Arrow Right: step by `step` increment
- Page Up / Page Down: step by `largeStep` increment
- Home: set volume to 0
- End: set volume to max

Scroll wheel support:

- **Mouse wheel / trackpad scroll**: adjusts volume by `wheelStep` increment (default `5`)

## Examples

Nest sub-components for full control over the slider’s DOM structure. This example includes a track, fill bar, draggable thumb, and a tooltip that shows the volume percentage on hover.

**App.tsx**

```tsx
import { Container, createPlayer, MuteButton, VolumeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function WithParts() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <MuteButton
          className="media-mute-button"
          render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
        />
        <VolumeSlider.Root className="media-volume-slider">
          <VolumeSlider.Track className="media-slider-track">
            <VolumeSlider.Fill className="media-slider-fill" />
          </VolumeSlider.Track>
          <VolumeSlider.Thumb className="media-slider-thumb" />
          <VolumeSlider.Value type="pointer" className="media-slider-value" />
        </VolumeSlider.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-mute-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-volume-slider {
  position: absolute;
  right: 10px;
  bottom: 10px;
  display: flex;
  align-items: center;
  width: 100px;
  height: 20px;
  cursor: pointer;
}

.media-slider-track {
  position: absolute;
  right: 0;
  left: 0;
  height: 4px;
  background: rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
  transition: height 150ms ease;
}

.media-volume-slider[data-interactive] .media-slider-track {
  height: 6px;
}

.media-slider-fill {
  position: absolute;
  top: 0;
  left: 0;
  width: var(--media-slider-fill);
  height: 100%;
  background: white;
  border-radius: 9999px;
}

.media-slider-thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.4);
  transform: translateX(-50%) scale(0);
  transition: transform 150ms ease;
}

.media-volume-slider[data-interactive] .media-slider-thumb {
  transform: translateX(-50%) scale(1);
}

.media-volume-slider[data-dragging] .media-slider-thumb {
  transform: translateX(-50%) scale(1.1);
}

.media-slider-value {
  position: absolute;
  bottom: 100%;
  left: var(--media-slider-pointer);
  padding: 2px 6px;
  margin-bottom: 6px;
  font-size: 12px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.8);
  border-radius: 4px;
  opacity: 0;
  transform: translateX(-50%);
  transition: opacity 150ms ease;
}

.media-volume-slider[data-pointing] .media-slider-value {
  opacity: 1;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Whether the slider is non-interactive. |
| `label` | `{ key: string; text: string } \| string \| ((state: SliderState) => Text \| string)` | `''` | Custom label for the slider. |
| `largeStep` | `number` | — | Large step increment (Page Up/Down keys). |
| `max` | `number` | — | |
| `min` | `number` | — | |
| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
| `step` | `number` | `DEFAULT_VOLUME_STEP` | Step increment for value changes (arrow keys). |
| `thumbAlignment` | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
| `value` | `number` | — | |
| `wheelStep` | `number` | `DEFAULT_VOLUME_STEP` | Step increment for wheel scrolling. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `value` | `number` | Current slider value in the min–max range. |
| `fillPercent` | `number` | Fill level as a percentage (0–100), derived from value. |
| `pointerPercent` | `number` | Pointer position as a percentage of the track (0–100). |
| `dragging` | `boolean` | Whether the user is actively dragging. |
| `pointing` | `boolean` | Whether the pointer is over the slider. |
| `interactive` | `boolean` | Whether dragging, pointing, or focus is active. |
| `orientation` | `'horizontal' \| 'vertical'` | Axis of slider movement. |
| `disabled` | `boolean` | Whether the slider is non-interactive. |
| `thumbAlignment` | `'center' \| 'edge'` | How the thumb aligns at the track edges. |
| `volume` | `number` | Volume level from 0 (silent) to 1 (max). |
| `muted` | `boolean` | Whether audio is muted. |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | |
| `hidden` | `boolean` | |

#### Data attributes

| Attribute | Type |
| --- | --- |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` |
| `data-hidden` | — |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-slider-fill` | Fill level percentage (0–100), representing the current volume level. |
| `--media-slider-pointer` | Pointer position percentage (0–100), tracking the cursor along the slider. |

### Fill

Displays the filled portion from start to the current value.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

### Track

Contains the slider's visual track and interactive hit zone.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays a formatted text representation of the slider value. Renders an `<output>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SliderState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `format` | `((value: number) => string)` | — | Custom formatter for the displayed value. Overrides the root's `formatValue`. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SliderState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SliderState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `type` | `'current' \| 'pointer'` | — | Which slider value to display: the current position or the pointer position. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-dragging` | — | Present when the user is actively dragging. |
| `data-pointing` | — | Present when the pointer is over the slider. |
| `data-interactive` | — | Present when dragging, pointing, or focus is active. |
| `data-orientation` | `'horizontal' \| 'vertical'` | Current axis of slider movement (`horizontal` or `vertical`). |
| `data-disabled` | — | Present when the slider is non-interactive. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/menu -->

# Menu

A composable menu component for settings, option selection, and actions

## Import

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

## Anatomy

A root menu owns one positioned Popup. Nested `Content` elements share that Popup with the root Content.

```tsx
<Menu.Root>
  <Menu.Trigger />
  <Menu.Popup>
    <Menu.Content>
      {/* Parent menu item that opens a submenu */}
      <Menu.Root>
        <Menu.Trigger />

        <Menu.Content>
          <Menu.Item>Back</Menu.Item>
          <Menu.RadioGroup>
            <Menu.GroupLabel />
            <Menu.RadioItem>
              <Menu.ItemIndicator />
            </Menu.RadioItem>
          </Menu.RadioGroup>
        </Menu.Content>
      </Menu.Root>

      {/* Other parent menu items */}
      <Menu.Group>
        <Menu.GroupLabel />
        <Menu.CheckboxItem>
          <Menu.ItemIndicator />
        </Menu.CheckboxItem>
      </Menu.Group>
      <Menu.Separator />
      <Menu.Item />
    </Menu.Content>
  </Menu.Popup>
</Menu.Root>
```

## Behavior

Menus open from a trigger and close when you select an item, click outside, move focus away, or press Escape. Root menus use `side` and `align` as their preferred placement. When the preferred side overflows the positioning boundary, the menu uses the opposite side if it has more space.

Root menus inside a [player container](https://videojs.org/docs/framework/react/reference/components/player-container) join its popup group. Opening one closes any other root menu or popover that is open in the same container. Submenus remain part of their root menu instead of registering separately.

Create a submenu by nesting another `Menu.Root` in the parent `Menu.Content`; its `Menu.Trigger` behaves as a parent item and its `Menu.Content` becomes the active Content.

Media option groups share their option state with the enclosing menu: the selected value, and whether the options are disabled, hidden, or available. The menu’s trigger inherits the disabled and hidden state and exposes `data-availability`, and the menu closes if its options disappear while open. See [PlaybackRateRadioGroup](https://videojs.org/docs/framework/react/reference/components/playback-rate-radio-group), [QualityRadioGroup](https://videojs.org/docs/framework/react/reference/components/quality-radio-group), [AudioTrackRadioGroup](https://videojs.org/docs/framework/react/reference/components/audio-track-radio-group), and [CaptionsRadioGroup](https://videojs.org/docs/framework/react/reference/components/captions-radio-group).

Wrap a submenu’s `Menu.Trigger` and `Menu.Content` in the group’s `Root` part, and render its `Value` part inside the trigger to show the current selection:

```tsx
<Menu.Root>
  <QualityRadioGroup.Root>
    <Menu.Trigger>
      Quality
      <QualityRadioGroup.Value />
    </Menu.Trigger>
    <Menu.Content>
      <QualityRadioGroup.Options renderItem={...} />
    </Menu.Content>
  </QualityRadioGroup.Root>
</Menu.Root>
```

## Styling

Use data attributes to style open state, highlighted items, selected radio items, and submenu views:

`data-highlighted` identifies the current menu item. Its value is `"pointer"` when pointer movement caused the highlight and an empty string for other highlights, including keyboard navigation and type-ahead search. Use `[data-highlighted]` to match any highlighted item or `[data-highlighted=""]` to match highlights that were not caused by pointer movement.

The root `Menu.Popup` receives `data-open`, `data-side`, and `data-align`. Each `Menu.Content` receives menu state such as `data-open` and `data-submenu`; a Content with an open logical child receives `data-child-open`.

Every navigable item receives `data-item`. Use `[data-item]` when one rule should target regular, radio, checkbox, and submenu-trigger items together.

```css
.menu-popup[data-open] {
  opacity: 1;
}

.menu-content[data-child-open] {
  translate: -100% 0;
}

.menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
  transition: background-color 100ms ease-in-out;
}

.menu-item[data-highlighted=""] {
  transition-duration: 0ms;
}

[role="menuitemradio"][aria-checked="true"] {
  font-weight: 600;
}
```

## Accessibility

Menu content renders with `role="menu"`. Items use `menuitem`, `menuitemradio`, or `menuitemcheckbox` roles. Radio and checkbox items reflect selection with `aria-checked`.

Keyboard controls:

- Enter / Space: Select the highlighted item.
- Arrow Up / Arrow Down: Move between items.
- Arrow Right: Open a submenu.
- Arrow Left: Return to the parent menu.
- Escape: Close the root menu or return from a submenu.

Use `Menu.GroupLabel` inside grouped choices so the group receives an accessible label.

## Examples

### Basic usage

**App.tsx**

```tsx
import {
  Container,
  createPlayer,
  Menu,
  useAudioTrackOptions,
  useCaptionsOptions,
  usePlaybackRateOptions,
  useQualityOptions,
} from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });
const src = 'https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8';

function SettingsMenu(): ReactNode {
  const playbackRate = usePlaybackRateOptions();
  const quality = useQualityOptions();
  const audioTrack = useAudioTrackOptions();
  const captions = useCaptionsOptions();
  const hasPlaybackRate = playbackRate?.state.availability === 'available';
  const hasQuality = quality?.state.availability === 'available';
  const hasAudioTrack = audioTrack?.state.availability === 'available';
  const hasCaptions = captions?.state.availability === 'available';
  if (!hasPlaybackRate && !hasQuality && !hasAudioTrack && !hasCaptions) return null;

  return (
    <Menu.Root side="top" align="end">
      <Menu.Trigger className="settings-trigger" aria-label="Settings" render={<button type="button" />}>
        Settings
      </Menu.Trigger>
      <Menu.Popup className="menu">
        <Menu.Content className="menu-content">
          {hasQuality ? (
            <Menu.Root>
              <Menu.Trigger
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Quality</span>
                    <span className="menu-value">
                      {quality.selectedLabel}
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Item className="menu-back">
                  <span aria-hidden="true">‹</span>
                  Quality
                </Menu.Item>
                <Menu.RadioGroup
                  className="menu-group"
                  value={quality.value}
                  onValueChange={quality.setValue}
                  aria-label="Quality"
                >
                  {quality.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>
                        {option.label}
                        {option.tier ? <sup className="menu-tier">{option.tier}</sup> : null}
                      </span>
                      {option.badge ? <span className="menu-badge">{option.badge}</span> : null}
                      <Menu.ItemIndicator
                        checked={option.value === quality.value}
                        forceMount
                        className="menu-indicator"
                      >
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          {hasAudioTrack ? (
            <Menu.Root>
              <Menu.Trigger
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Audio</span>
                    <span className="menu-value">
                      {audioTrack.selectedLabel}
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Item className="menu-back">
                  <span aria-hidden="true">‹</span>
                  Audio
                </Menu.Item>
                <Menu.RadioGroup
                  className="menu-group"
                  value={audioTrack.value}
                  onValueChange={audioTrack.setValue}
                  aria-label="Audio tracks"
                >
                  {audioTrack.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>{option.label}</span>
                      <Menu.ItemIndicator
                        checked={option.value === audioTrack.value}
                        forceMount
                        className="menu-indicator"
                      >
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          {hasPlaybackRate ? (
            <Menu.Root>
              <Menu.Trigger
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Speed</span>
                    <span className="menu-value">
                      {playbackRate.selectedLabel}
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Item className="menu-back">
                  <span aria-hidden="true">‹</span>
                  Speed
                </Menu.Item>
                <Menu.RadioGroup
                  className="menu-group"
                  value={playbackRate.value}
                  onValueChange={playbackRate.setValue}
                  aria-label="Playback rate"
                >
                  {playbackRate.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>{option.label}</span>
                      <Menu.ItemIndicator
                        checked={option.value === playbackRate.value}
                        forceMount
                        className="menu-indicator"
                      >
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          {hasCaptions ? (
            <Menu.Root>
              <Menu.Trigger
                className="menu-item"
                render={(props) => (
                  <div {...props}>
                    <span>Captions</span>
                    <span className="menu-value">
                      {captions.selectedLabel}
                      <span aria-hidden="true">›</span>
                    </span>
                  </div>
                )}
              />
              <Menu.Content className="menu-panel">
                <Menu.Item className="menu-back">
                  <span aria-hidden="true">‹</span>
                  Captions
                </Menu.Item>
                <Menu.RadioGroup
                  className="menu-group"
                  value={captions.value}
                  onValueChange={captions.setValue}
                  aria-label="Captions"
                >
                  {captions.options.map((option) => (
                    <Menu.RadioItem
                      key={option.value}
                      value={option.value}
                      disabled={option.disabled}
                      className="menu-item"
                    >
                      <span>{option.label}</span>
                      <Menu.ItemIndicator
                        checked={option.value === captions.value}
                        forceMount
                        className="menu-indicator"
                      >
                        ✓
                      </Menu.ItemIndicator>
                    </Menu.RadioItem>
                  ))}
                </Menu.RadioGroup>
              </Menu.Content>
            </Menu.Root>
          ) : null}

          <Menu.Item className="menu-item" onSelect={() => navigator.clipboard?.writeText(window.location.href)}>
            Copy link
          </Menu.Item>
        </Menu.Content>
      </Menu.Popup>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop>
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
          <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srcLang="es" label="Spanish" />
        </HlsJsVideo>
        <div className="menu-bar">
          <SettingsMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.settings-trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.35);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.menu {
  --media-menu-side-offset: 8px;
  --menu-transition-duration: 220ms;
  position: relative;
  box-sizing: border-box;
  width: var(--media-menu-width);
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  height: var(--media-menu-height);
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: hidden;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: width, height, opacity, filter;
}

.menu-content,
.menu-panel {
  position: absolute;
  inset: 0;
  display: grid;
  gap: 2px;
  padding: 6px;
  overflow: auto;
  overscroll-behavior: none;
  outline: none;
  translate: 0 0;
  transition-timing-function: ease-in-out;
  transition-duration: var(--menu-transition-duration);
  transition-property: translate, filter;
}

.menu-content[data-child-open] {
  filter: blur(8px);
  translate: -100% 0;
}

.menu-panel[data-submenu] {
  z-index: 1;
}

.menu-panel[data-submenu][data-starting-style],
.menu-panel[data-submenu][data-ending-style] {
  overflow: hidden;
  pointer-events: none;
  filter: blur(8px);
  translate: 100% 0;
}

.menu-item,
.menu-back {
  display: flex;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted],
.menu-back:hover {
  background: rgba(255, 255, 255, 0.16);
}

.menu-back {
  gap: 8px;
  justify-content: flex-start;
}

.menu-value {
  display: inline-flex;
  gap: 8px;
  align-items: center;
  color: rgba(255, 255, 255, 0.72);
}

.menu-group {
  display: grid;
  gap: 2px;
}

.menu-tier {
  margin-left: 2px;
  font-size: 10px;
}

.menu-badge {
  margin-left: auto;
  color: rgba(255, 255, 255, 0.72);
}

.menu-back [aria-hidden],
[role="menuitemradio"] [aria-hidden],
.menu-item [aria-hidden] {
  font-size: 18px;
  line-height: 1;
  color: rgba(255, 255, 255, 0.72);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment along the trigger's edge. Root menus only. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the root menu popup. |
| `closeOnEscape` | `boolean` | `true` | Close the menu when Escape is pressed at root level. |
| `closeOnOutsideClick` | `boolean` | `true` | Close the menu when clicking outside. Root menus only. |
| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled). |
| `open` | `boolean` | `false` | Controlled open state. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Preferred side of the trigger for the menu. Root menus only. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right' \| undefined` | Preferred side of the trigger for the menu. Root menus only. |
| `align` | `'start' \| 'center' \| 'end' \| undefined` | |
| `isSubmenu` | `boolean` | Whether this menu is nested inside another menu's content. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-popover-side-offset` | Distance between the popup and the trigger along the side axis. |
| `--media-popover-align-offset` | Distance between the popup and the trigger along the alignment axis. |
| `--media-popover-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
| `--media-popover-anchor-width` | Width of the trigger, set by popup positioning. |
| `--media-popover-anchor-height` | Height of the trigger, set by popup positioning. |
| `--media-menu-width` | Width of the active menu panel (px). |
| `--media-menu-height` | Height of the active menu panel (px). |
| `--media-menu-available-width` | Width available within the positioning boundary (px). |
| `--media-menu-available-height` | Height available within the positioning boundary (px). |

### CheckboxItem

A checkbox-style menu item. Renders a `<div>` with `role="menuitemcheckbox"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the item is currently checked. |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `disabled` | `boolean` | — | Whether the item is disabled. |
| `onCheckedChange` | `((checked: boolean) => void)` | — | Called when the checked state should change. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |

### Content

Accessible item and focus scope for exactly one root or nested menu page.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Group

Groups related menu items. Renders a `<div>` with `role="group"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### GroupLabel

Non-interactive label for a group of items. Renders a `<div>`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Item

A single action in the menu. Renders a `<div>` with `role="menuitem"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `disabled` | `boolean` | — | Whether the item is disabled. |
| `onSelect` | `(() => void)` | — | Called when the item is selected. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |

### ItemIndicator

Visual indicator for a checked state. Only renders when `checked` is `true` (or `forceMount` is set).

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the indicator is currently shown. Typically bound to the parent item's checked state. |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `forceMount` | `boolean` | — | When `true`, renders even when unchecked (useful for animating out). Defaults to `false`. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Popup

Positioned menu surface that contains one or more sibling Content pages.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `keepMounted` | `boolean` | — | Keep the popup mounted, hidden, and inert while closed. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### RadioGroup

A group of mutually exclusive radio items. Renders a `<div>` with `role="group"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `onValueChange` | `((value: string) => void)` | — | Called when the user selects a radio item. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `value` | `string` | — | The currently selected value. |

### RadioItem

A radio-style menu item. Renders a `<div>` with `role="menuitemradio"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `disabled` | `boolean` | — | Whether the item is disabled. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |
| `value` | `string` | — | The value this item represents. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |

### Separator

Visual divider between groups of items. Renders a `<div>` with `role="separator"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Trigger

Button that toggles the menu visibility. At root level renders a `<button>`. When inside a parent menu (as a submenu trigger), renders as a `<div role="menuitem">` that opens the submenu on click or ArrowRight.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: MenuState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `disabled` | `boolean` | — | Disables the trigger. |
| `onClick` | `MouseEventHandler<HTMLButtonElement \| HTMLDivElement>` | — | |
| `onKeyDown` | `KeyboardEventHandler<HTMLButtonElement \| HTMLDivElement>` | — | |
| `render` | `ReactElement \| ((props: HTMLProps, state: MenuState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: MenuState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-item` | Present on all navigable item types: Item, RadioItem, CheckboxItem, and the Trigger when acting as a submenu trigger inside a parent menu. Use `[data-item]` as a shared selector to target all item types at once. |
| `data-highlighted` | Present when the item is highlighted. Set to `pointer` when pointer movement caused the highlight; otherwise empty. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/popover -->

# Popover

A popover component for displaying contextual content anchored to a trigger

## Import

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

## Anatomy

```tsx
<Popover.Root>
  <Popover.Trigger>Open</Popover.Trigger>
  <Popover.Popup className="popup">
    <Popover.Arrow />
    Content
  </Popover.Popup>
</Popover.Root>
```

## Behavior

Displays contextual content anchored to a trigger element. By default, opens on click and closes when clicking outside, pressing Escape, or when the trigger loses focus.

Set `openOnHover` to open on pointer hover instead of click. Use `delay` and `closeDelay` to control timing for hover interactions.

Popovers inside a [player container](https://videojs.org/docs/framework/react/reference/components/player-container) join its popup group. Opening one closes any other popover or root menu that is open in the same container. A popover outside the container still opens and closes normally, but it is not coordinated with that group.

The `side` and `align` props control the preferred popup placement relative to the trigger. When the preferred side overflows the positioning boundary, the popup uses the opposite side if it has more space.

The component is composed from four parts: `Root` manages state, `Trigger` toggles the popover, `Popup` contains the content, and `Arrow` renders a directional arrow.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/react/reference/components/popover#root-css-custom-properties) for positioning offsets:

`Popover.Popup` accepts `className`. The anatomy above uses `popup`:

```css
.popup {
  --media-popover-side-offset: 8px;
  --media-popover-align-offset: 0px;
  --media-popover-boundary-offset: 8px;
}
```

Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:

```css
.popup[data-open] {
  display: block;
}
.popup[data-starting-style] {
  opacity: 0;
}
.popup[data-ending-style] {
  opacity: 0;
}
.popup[data-side="top"] {
  transform-origin: bottom center;
}
.popup[data-side="bottom"] {
  transform-origin: top center;
}
```

## Accessibility

The trigger receives `aria-expanded` reflecting the open state. When `modal` is set, the popup receives `aria-modal="true"`. Closing via Escape is enabled by default and can be disabled with `closeOnEscape={false}`.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, Popover } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <div className="bar">
          <Popover.Root>
            <Popover.Trigger className="trigger">Settings</Popover.Trigger>
            <Popover.Popup className="popup">
              <Popover.Arrow className="arrow" />
              <div className="content">Popover content</div>
            </Popover.Popup>
          </Popover.Root>
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.bar {
  position: absolute;
  bottom: 10px;
  left: 10px;
}

.trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.popup {
  /* Reset UA [popover] defaults */
  --media-popover-side-offset: 8px;
  padding: 12px 16px;
  margin: 0;
  font-size: 14px;
  color: white;

  background: rgba(0, 0, 0, 0.85);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

.arrow {
  fill: rgba(0, 0, 0, 0.85);
}

.content {
  white-space: nowrap;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the popup along the trigger's edge. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the popup position. |
| `closeDelay` | `number` | `0` | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` | `boolean` | `true` | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` | `boolean` | `true` | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
| `delay` | `number` | `300` | Delay in ms before opening on hover. |
| `modal` | `boolean \| 'trap-focus'` | `false` | - `false` (default): non-modal; background content remains interactive.<br>- `true`: modal; sets `aria-modal="true"` on the popup.<br>- `'trap-focus'`: reserved for future focus-trapping behavior. |
| `open` | `boolean` | `false` | Controlled open state. When set, the consumer is responsible for toggling. |
| `openOnHover` | `boolean` | `false` | Open the popup on pointer hover instead of click. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the popup. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the popup. |
| `align` | `'start' \| 'center' \| 'end'` | |
| `modal` | `boolean \| 'trap-focus'` | |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the popover after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popover is aligned relative to the specified side. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-popover-side-offset` | Distance between the popup and the trigger along the side axis. |
| `--media-popover-align-offset` | Distance between the popup and the trigger along the alignment axis. |
| `--media-popover-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
| `--media-popover-anchor-width` | The anchor element's width. |
| `--media-popover-anchor-height` | The anchor element's height. |
| `--media-popover-available-width` | Available width between the trigger and the boundary edge. |
| `--media-popover-available-height` | Available height between the trigger and the boundary edge. |

### Arrow

Decorative arrow pointing from the popup toward the trigger. Hidden from assistive technology.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Popup

Container for the popover content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the popover after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popover is aligned relative to the specified side. |

### Trigger

Button that toggles the popover visibility. Renders a `<button>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the popover after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popover is aligned relative to the specified side. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/volume-popover -->

# VolumePopover

A volume-aware popover that keeps mute available when volume level controls are unavailable

## Import

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

## Anatomy

```tsx
<VolumePopover.Root>
  <VolumePopover.Trigger render={<MuteButton />} />
  <VolumePopover.Popup>
    <VolumeSlider.Root />
  </VolumePopover.Popup>
</VolumePopover.Root>
```

## Behavior

`VolumePopover` combines [popover behavior](https://videojs.org/docs/framework/react/reference/components/popover) with volume availability. When volume level controls are unavailable, it closes and omits the popup while keeping the mute trigger rendered. This lets media with fixed volume keep mute control without exposing a nonfunctional slider.

## Styling

The popup reflects `data-availability="available"` while it can render volume controls.

React renders the popup as a standard `<div>`. Add a `className` to select it:

```css
.volume-popup[data-open] {
  opacity: 1;
}
```

## Accessibility

The trigger receives `aria-haspopup`, `aria-expanded`, and `aria-controls` while the volume popup is available. When only mute is available, the trigger keeps the mute button’s own accessible name and behavior without popup ARIA.

## Examples

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, MuteButton, VolumePopover, VolumeSlider } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-volume-popover-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <div className="react-volume-popover-basic__controls">
          <VolumePopover.Root openOnHover side="top">
            <VolumePopover.Trigger
              className="react-volume-popover-basic__trigger"
              render={
                <MuteButton render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>} />
              }
            />
            <VolumePopover.Popup className="react-volume-popover-basic__popup">
              <VolumeSlider.Root orientation="vertical" className="react-volume-popover-basic__slider">
                <VolumeSlider.Track className="react-volume-popover-basic__track">
                  <VolumeSlider.Fill className="react-volume-popover-basic__fill" />
                </VolumeSlider.Track>
                <VolumeSlider.Thumb className="react-volume-popover-basic__thumb" />
              </VolumeSlider.Root>
            </VolumePopover.Popup>
          </VolumePopover.Root>
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-volume-popover-basic {
  position: relative;
}

.react-volume-popover-basic video {
  width: 100%;
}

.react-volume-popover-basic__controls {
  position: absolute;
  bottom: 10px;
  left: 10px;
}

.react-volume-popover-basic__trigger {
  padding: 8px 20px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 70%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.react-volume-popover-basic__popup {
  --media-popover-side-offset: 8px;
  width: 40px;
  height: 120px;
  padding: 12px;
  margin: 0;
  background: rgb(0 0 0 / 85%);
  border: 0;
  border-radius: 8px;
}

.react-volume-popover-basic__slider {
  position: relative;
  width: 16px;
  height: 96px;
  margin: auto;
  cursor: pointer;
}

.react-volume-popover-basic__track {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 6px;
  width: 4px;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.react-volume-popover-basic__fill {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  height: var(--media-slider-fill);
  background: white;
  border-radius: inherit;
}

.react-volume-popover-basic__thumb {
  position: absolute;
  bottom: var(--media-slider-fill);
  left: 1px;
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  transform: translateY(50%);
}
```

## API Reference

### Root

Owns the popover interaction lifecycle and provides volume availability to the parts.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | — | Alignment of the popup along the trigger's edge. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the popup position. |
| `closeDelay` | `number` | — | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` | `boolean` | — | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` | `boolean` | — | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` | `boolean` | — | Initial open state for uncontrolled usage. |
| `delay` | `number` | — | Delay in ms before opening on hover. |
| `modal` | `boolean \| 'trap-focus'` | — | - `false` (default): non-modal; background content remains interactive.<br>- `true`: modal; sets `aria-modal="true"` on the popup.<br>- `'trap-focus'`: reserved for future focus-trapping behavior. |
| `open` | `boolean` | — | Controlled open state. When set, the consumer is responsible for toggling. |
| `openOnHover` | `boolean` | — | Open the popup on pointer hover instead of click. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | — | Preferred side of the trigger for the popup. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | |
| `status` | `'idle' \| 'starting' \| 'ending'` | |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the popup. |
| `align` | `'start' \| 'center' \| 'end'` | |
| `modal` | `boolean \| 'trap-focus'` | |
| `availability` | `'available' \| 'unavailable' \| 'unsupported'` | Whether volume level controls are available. |
| `hidden` | `boolean` | Whether the popup is hidden because volume level controls are unavailable. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the popover is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the popup is aligned relative to its side. |
| `data-starting-style` | — | Present during the open transition. |
| `data-ending-style` | — | Present during the close transition. |
| `data-availability` | `'available' \| 'unavailable' \| 'unsupported'` | Indicates volume control availability (`available`, `unavailable`, or `unsupported`). |
| `data-hidden` | — | Present when volume level controls are unavailable. |

### Popup

Positioned volume content. Omitted when volume level controls are unavailable.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Trigger

Opens the volume popup, or renders its mute-button fallback when volume level controls are unavailable.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PopoverState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PopoverState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PopoverState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/audio-track-radio-group -->

# AudioTrackRadioGroup

A menu radio group for selecting an audio track

Creates radio items from the player audio track state and selects the enabled track.

## Import

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

## Anatomy

```tsx
<AudioTrackRadioGroup.Root>
  <Menu.Trigger>
    <AudioTrackRadioGroup.Value />
  </Menu.Trigger>
  <Menu.Content>
    <AudioTrackRadioGroup.Options
      renderItem={(props, item) => (
        <Menu.RadioItem {...props}>
          {item.label}
          <Menu.ItemIndicator checked={item.checked} />
        </Menu.RadioItem>
      )}
    />
  </Menu.Content>
</AudioTrackRadioGroup.Root>
```

## Behavior

The group is available when the configured media exposes more than one audio track. Labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.

`AudioTrackRadioGroup.Root` uses [`useAudioTrackOptions`](https://videojs.org/docs/framework/react/reference/api/use-audio-track-options) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `AudioTrackRadioGroup.Options` renders the items: its required `renderItem` callback renders the [`Menu.RadioItem`](https://videojs.org/docs/framework/react/reference/components/menu) root and receives item state containing the translated `label` and current `checked` value. `AudioTrackRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [audio track feature](https://videojs.org/docs/framework/react/reference/api/feature-audio-track) is not configured.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-audio-track` | `string` | Current audio track value. |
| `data-disabled` | Present / absent | Present when audio track selection is disabled. |
| `data-hidden` | Present / absent | Present when multiple audio tracks are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether multiple audio tracks are available. |

Unavailable groups receive the native `hidden` attribute.

## Accessibility

The group uses the menu radio group pattern.

`AudioTrackRadioGroup.Options` receives its accessible label from the `label` prop on `AudioTrackRadioGroup.Root` or defaults to `Audio`. Override it with `aria-label` or `aria-labelledby` on `AudioTrackRadioGroup.Options`.

## Examples

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, Menu, AudioTrackRadioGroup } from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });
const src = 'https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8';

function AudioMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <AudioTrackRadioGroup.Root>
        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
          Audio
          <AudioTrackRadioGroup.Value className="menu-hint" />
        </Menu.Trigger>
        <Menu.Popup className="menu">
          <Menu.Content>
            <AudioTrackRadioGroup.Options
              className="menu-group"
              renderItem={(props, item) => (
                <Menu.RadioItem {...props} className="menu-item">
                  {item.label}
                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                    ✓
                  </Menu.ItemIndicator>
                </Menu.RadioItem>
              )}
            />
          </Menu.Content>
        </Menu.Popup>
      </AudioTrackRadioGroup.Root>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
        <div className="menu-bar">
          <AudioMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.settings-trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.35);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.menu-hint {
  margin-left: 8px;
  color: rgba(0, 0, 0, 0.6);
}

.menu-hint:empty {
  display: none;
}

.menu {
  --media-menu-side-offset: 8px;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

.menu-group {
  display: grid;
  gap: 2px;
}

.menu-item {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

## API Reference

### Root

Owns audio-track option state and shares it with an enclosing menu. Does not render a DOM element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether audio track selection is disabled. |
| `formatTrack` | `((track: MediaAudioTrack) => Text \| string)` | `formatTrackLabel` | Custom formatter for visible track labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: AudioTrackRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-audio-track` | `string` | Current audio track value. |
| `data-disabled` | — | Present when audio track selection is disabled. |
| `data-hidden` | — | Present when audio track selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable'` | Indicates audio track availability (`available` or `unavailable`). |

### Options

Renders menu radio items for the player's available audio tracks.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: AudioTrackRadioGroupState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: AudioTrackRadioGroupState) => ReactElement \| null)` | — | Render prop for custom element. |
| `renderItem` | `((props: AudioTrackRadioGroupItemProps, state: AudioTrackRadioGroupItemState) => ReactElement)` | — | Render one consumer-owned menu radio item for every audio track. |
| `style` | `CSSProperties \| ((state: AudioTrackRadioGroupState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays the selected audio-track label.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: AudioTrackOptionsResult) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: AudioTrackOptionsResult) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: AudioTrackOptionsResult) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/captions-radio-group -->

# CaptionsRadioGroup

A menu radio group for selecting caption and subtitle tracks

Creates radio items from the player text track state and selects the showing caption or subtitle track.

## Import

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

## Anatomy

```tsx
<Menu.Root>
  <CaptionsRadioGroup.Root>
    <Menu.Trigger>
      <CaptionsRadioGroup.Value />
    </Menu.Trigger>
    <Menu.Popup>
      <Menu.Content>
        <CaptionsRadioGroup.Options
          renderItem={(props, item) => (
            <Menu.RadioItem {...props}>
              {item.label}
              <Menu.ItemIndicator checked={item.checked} />
            </Menu.RadioItem>
          )}
        />
      </Menu.Content>
    </Menu.Popup>
  </CaptionsRadioGroup.Root>
</Menu.Root>
```

## Behavior

The group is available when the configured media exposes at least one caption or subtitle track. The first generated option is `Off`; selecting it hides captions. Track labels use the track label, then language, then kind. Pass `formatTrack` to customize the visible labels.

`CaptionsRadioGroup.Root` uses [`useCaptionsOptions`](https://videojs.org/docs/framework/react/reference/api/use-captions-options) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `CaptionsRadioGroup.Options` renders the items, including `Off`: its required `renderItem` callback renders the [`Menu.RadioItem`](https://videojs.org/docs/framework/react/reference/components/menu) root and receives item state containing the translated `label` and current `checked` value. `CaptionsRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [text tracks feature](https://videojs.org/docs/framework/react/reference/api/feature-text-tracks) is not configured.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-active` | Present / absent | Present when captions are enabled. |
| `data-disabled` | Present / absent | Present when track selection is disabled. |
| `data-hidden` | Present / absent | Present when caption or subtitle tracks are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether caption or subtitle tracks are available. |

Unavailable groups receive the native `hidden` attribute.

## Accessibility

The group uses the menu radio group pattern.

`CaptionsRadioGroup.Options` receives its accessible label from the `label` prop on `CaptionsRadioGroup.Root` or defaults to `Captions`. Override it with `aria-label` or `aria-labelledby` on `CaptionsRadioGroup.Options`.

## Examples

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, Menu, CaptionsRadioGroup } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });

function CaptionsMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <CaptionsRadioGroup.Root>
        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
          Captions
          <CaptionsRadioGroup.Value className="menu-hint" />
        </Menu.Trigger>
        <Menu.Popup className="menu">
          <Menu.Content>
            <CaptionsRadioGroup.Options
              className="menu-group"
              renderItem={(props, item) => (
                <Menu.RadioItem {...props} className="menu-item">
                  {item.label}
                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                    ✓
                  </Menu.ItemIndicator>
                </Menu.RadioItem>
              )}
            />
          </Menu.Content>
        </Menu.Popup>
      </CaptionsRadioGroup.Root>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
          <track kind="subtitles" src="/docs/demos/captions-button/captions.vtt" srcLang="es" label="Spanish" />
        </Video>
        <div className="menu-bar">
          <CaptionsMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.settings-trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.35);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.menu-hint {
  margin-left: 8px;
  color: rgba(0, 0, 0, 0.6);
}

.menu-hint:empty {
  display: none;
}

.menu {
  --media-menu-side-offset: 8px;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

.menu-group {
  display: grid;
  gap: 2px;
}

.menu-item {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

## API Reference

### Root

Owns captions option state and shares it with an enclosing menu. Does not render a DOM element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether track selection is disabled. |
| `formatTrack` | `((track: MediaTextTrack) => Text \| string)` | `formatTrackLabel` | Custom formatter for visible track labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: CaptionsRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `subtitlesShowing` | `boolean` | Whether a captions/subtitles track is showing. |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-active` | — | Present when captions are enabled. |
| `data-disabled` | — | Present when track selection is disabled. |
| `data-hidden` | — | Present when track selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable'` | Indicates captions availability (`available` or `unavailable`). |

### Options

Renders menu radio items for the player's captions and subtitles tracks.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: CaptionsRadioGroupState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: CaptionsRadioGroupState) => ReactElement \| null)` | — | Render prop for custom element. |
| `renderItem` | `((props: CaptionsRadioGroupItemProps, state: CaptionsRadioGroupItemState) => ReactElement)` | — | Render one consumer-owned menu radio item for every captions option. |
| `style` | `CSSProperties \| ((state: CaptionsRadioGroupState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays the selected captions label.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: CaptionsOptionsResult) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: CaptionsOptionsResult) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: CaptionsOptionsResult) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/playback-rate-radio-group -->

# PlaybackRateRadioGroup

A menu radio group for selecting playback speed

Creates radio items from the player playback rate state and selects the playback speed.

## Import

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

## Anatomy

```tsx
<PlaybackRateRadioGroup.Root>
  <Menu.Trigger>
    <PlaybackRateRadioGroup.Value />
  </Menu.Trigger>
  <Menu.Content>
    <PlaybackRateRadioGroup.Options
      renderItem={(props, item) => (
        <Menu.RadioItem {...props}>
          {item.label}
          <Menu.ItemIndicator checked={item.checked} />
        </Menu.RadioItem>
      )}
    />
  </Menu.Content>
</PlaybackRateRadioGroup.Root>
```

## Behavior

The group is available when the configured media exposes playback rates. Option labels default to the rate followed by a multiplication sign (e.g. `1.5×`); pass `formatRate` to customize them.

`PlaybackRateRadioGroup.Root` uses [`usePlaybackRateOptions`](https://videojs.org/docs/framework/react/reference/api/use-playback-rate-options) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `PlaybackRateRadioGroup.Options` renders the items: its required `renderItem` callback renders the [`Menu.RadioItem`](https://videojs.org/docs/framework/react/reference/components/menu) root and receives item state containing the translated `label` and current `checked` value. `PlaybackRateRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [playback rate feature](https://videojs.org/docs/framework/react/reference/api/feature-playback-rate) is not configured.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-rate` | `number` | Current playback rate. |
| `data-disabled` | Present / absent | Present when playback rate selection is disabled. |
| `data-hidden` | Present / absent | Present when playback-rate selection is unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether playback rates are available. |

Unavailable groups receive the native `hidden` attribute.

## Accessibility

The group uses the menu radio group pattern.

`PlaybackRateRadioGroup.Options` receives its accessible label from the `label` prop on `PlaybackRateRadioGroup.Root` or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby` on `PlaybackRateRadioGroup.Options`.

## Examples

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, Menu, PlaybackRateRadioGroup } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });

function SpeedMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <PlaybackRateRadioGroup.Root>
        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
          Speed
          <PlaybackRateRadioGroup.Value className="menu-hint" />
        </Menu.Trigger>
        <Menu.Popup className="menu">
          <Menu.Content>
            <PlaybackRateRadioGroup.Options
              className="menu-group"
              renderItem={(props, item) => (
                <Menu.RadioItem {...props} className="menu-item">
                  {item.label}
                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                    ✓
                  </Menu.ItemIndicator>
                </Menu.RadioItem>
              )}
            />
          </Menu.Content>
        </Menu.Popup>
      </PlaybackRateRadioGroup.Root>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <div className="menu-bar">
          <SpeedMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.settings-trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.35);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.menu-hint {
  margin-left: 8px;
  color: rgba(0, 0, 0, 0.6);
}

.menu-hint:empty {
  display: none;
}

.menu {
  --media-menu-side-offset: 8px;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

.menu-group {
  display: grid;
  gap: 2px;
}

.menu-item {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

## API Reference

### Root

Owns playback-rate option state and shares it with an enclosing menu. Does not render a DOM element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether playback rate selection is disabled. |
| `formatRate` | `((rate: number) => string)` | `formatPlaybackRate` | Custom formatter for visible playback rate labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: PlaybackRateRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |
| `rate` | `number` | |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-rate` | `number` | Current playback rate. |
| `data-disabled` | — | Present when playback rate selection is disabled. |
| `data-hidden` | — | Present when playback rate selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable'` | Indicates playback rate availability (`available` or `unavailable`). |

### Options

Renders menu radio items for the player's available playback rates.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PlaybackRateRadioGroupState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PlaybackRateRadioGroupState) => ReactElement \| null)` | — | Render prop for custom element. |
| `renderItem` | `((props: PlaybackRateRadioGroupItemProps, state: PlaybackRateRadioGroupItemState) => ReactElement)` | — | Render one consumer-owned menu radio item for every playback rate. |
| `style` | `CSSProperties \| ((state: PlaybackRateRadioGroupState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays the selected playback-rate label.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PlaybackRateOptionsResult) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PlaybackRateOptionsResult) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PlaybackRateOptionsResult) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/quality-radio-group -->

# QualityRadioGroup

A menu radio group for selecting video quality

Creates radio items from the player video rendition state and selects automatic or manual quality.

## Import

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

## Anatomy

```tsx
<QualityRadioGroup.Root>
  <Menu.Trigger>
    <QualityRadioGroup.Value />
  </Menu.Trigger>
  <Menu.Content>
    <QualityRadioGroup.Options
      renderItem={(props, item) => (
        <Menu.RadioItem {...props}>
          {item.label}
          <Menu.ItemIndicator checked={item.checked} />
        </Menu.RadioItem>
      )}
    />
  </Menu.Content>
</QualityRadioGroup.Root>
```

## Behavior

The group is available when the configured media exposes more than one video rendition. The first generated option is `Auto`; selecting it returns control to adaptive bitrate selection. Pass `formatRendition` to customize visible rendition labels.

`QualityRadioGroup.Root` uses [`useQualityOptions`](https://videojs.org/docs/framework/react/reference/api/use-quality-options) to own selection and renders no element. Wrap the menu’s `Menu.Trigger` and `Menu.Content` in it so the trigger inherits the group’s disabled and hidden state and exposes `data-availability`. `QualityRadioGroup.Options` renders the items: its required `renderItem` callback renders the [`Menu.RadioItem`](https://videojs.org/docs/framework/react/reference/components/menu) root and receives item state containing the translated `label`, optional `tier` and `badge`, and current `checked` value. `QualityRadioGroup.Value` displays the selected label, typically inside the trigger. `Options` and `Value` render `null` when the [quality feature](https://videojs.org/docs/framework/react/reference/api/feature-quality) is not configured.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-quality` | `string` | Current quality value. |
| `data-disabled` | Present / absent | Present when quality selection is disabled. |
| `data-hidden` | Present / absent | Present when multiple renditions are unavailable. |
| `data-availability` | `"available"` / `"unavailable"` | Whether multiple renditions are available. |

Unavailable groups receive the native `hidden` attribute.

## Accessibility

The group uses the menu radio group pattern.

`QualityRadioGroup.Options` receives its accessible label from the `label` prop on `QualityRadioGroup.Root` or defaults to `Quality`. Override it with `aria-label` or `aria-labelledby` on `QualityRadioGroup.Options`.

## Examples

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, Menu, QualityRadioGroup } from '@videojs/react';
import { HlsJsVideo } from '@videojs/react/media/hlsjs-video';
import { videoFeatures } from '@videojs/react/video';
import type { ReactNode } from 'react';

const { Player } = createPlayer({ features: videoFeatures });
const src = 'https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8';

function QualityMenu(): ReactNode {
  return (
    <Menu.Root side="top" align="end">
      <QualityRadioGroup.Root>
        <Menu.Trigger className="settings-trigger" render={<button type="button" />}>
          Quality
          <QualityRadioGroup.Value className="menu-hint" />
        </Menu.Trigger>
        <Menu.Popup className="menu">
          <Menu.Content>
            <QualityRadioGroup.Options
              className="menu-group"
              renderItem={(props, item) => (
                <Menu.RadioItem {...props} className="menu-item">
                  <span>
                    {item.label}
                    {item.tier ? <sup className="menu-tier">{item.tier}</sup> : null}
                  </span>
                  {item.badge ? <span className="menu-badge">{item.badge}</span> : null}
                  <Menu.ItemIndicator checked={item.checked} forceMount className="menu-indicator">
                    ✓
                  </Menu.ItemIndicator>
                </Menu.RadioItem>
              )}
            />
          </Menu.Content>
        </Menu.Popup>
      </QualityRadioGroup.Root>
    </Menu.Root>
  );
}

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <HlsJsVideo src={src} autoPlay crossOrigin="anonymous" muted playsInline loop />
        <div className="menu-bar">
          <QualityMenu />
        </div>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.settings-trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.35);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.menu-hint {
  margin-left: 8px;
  color: rgba(0, 0, 0, 0.6);
}

.menu-hint:empty {
  display: none;
}

.menu {
  --media-menu-side-offset: 8px;
  box-sizing: border-box;
  display: grid;
  gap: 2px;
  min-width: 180px;
  max-width: var(--media-menu-available-width, var(--media-popover-available-width, none));
  max-height: var(--media-menu-available-height, var(--media-popover-available-height, none));
  padding: 6px;
  margin: 0;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  border: 0;
  border-radius: 8px;
  backdrop-filter: blur(10px);
}

.menu-group {
  display: grid;
  gap: 2px;
}

.menu-item {
  display: flex;
  gap: 8px;
  align-items: center;
  justify-content: space-between;
  min-height: 32px;
  padding: 0 10px;
  font: inherit;
  color: inherit;
  cursor: pointer;
  background: none;
  border: 0;
  border-radius: 6px;
}

.menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
}

.menu-tier {
  margin-left: 2px;
  font-size: 10px;
}

.menu-badge {
  margin-left: auto;
  color: rgba(255, 255, 255, 0.72);
}

.menu-indicator {
  opacity: 0;
}

[role="menuitemradio"][aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

## API Reference

### Root

Owns quality option state and shares it with an enclosing menu. Does not render a DOM element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether quality selection is disabled. |
| `formatRendition` | `((rendition: MediaVideoRendition) => Text \| string)` | `formatRenditionLabel` | Custom formatter for visible rendition labels. |
| `label` | `{ key: string; text: string } \| string \| ((state: QualityRadioGroupState) => Text \| string)` | `''` | Custom label for the options group. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `label` | `{ key: string; text: string } \| string` | |
| `value` | `string` | Current radio-group value. |
| `options` | `readonly Option[]` | Ordered options displayed by platform adapters. |
| `disabled` | `boolean` | Whether the entire option group is disabled. |
| `hidden` | `boolean` | Whether the option group is hidden because no meaningful selection is available. |
| `availability` | `'available' \| 'unavailable'` | Whether the media exposes a meaningful selection. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-quality` | `string` | Current quality value. |
| `data-disabled` | — | Present when quality selection is disabled. |
| `data-hidden` | — | Present when quality selection is unavailable. |
| `data-availability` | `'available' \| 'unavailable'` | Indicates quality availability (`available` or `unavailable`). |

### Options

Renders menu radio items for the player's video renditions.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: QualityRadioGroupState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: QualityRadioGroupState) => ReactElement \| null)` | — | Render prop for custom element. |
| `renderItem` | `((props: QualityRadioGroupItemProps, state: QualityRadioGroupItemState) => ReactElement)` | — | Render one consumer-owned menu radio item for every quality option. |
| `style` | `CSSProperties \| ((state: QualityRadioGroupState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

Displays the selected quality label.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: QualityOptionsResult) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: QualityOptionsResult) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: QualityOptionsResult) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/time -->

# Time

Time display components for showing current time, duration, and remaining time in a video player

## Import

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

## Anatomy

```tsx
<Time.Group>
  <Time.Value type="current" />
  <Time.Separator />
  <Time.Value type="duration" />
</Time.Group>
```

## Behavior

Three display types — `current`, `duration`, and `remaining` — in digital format with smart padding:

- **Hours** are never padded (`1:05:30`, not `01:05:30`)
- **Minutes** are padded when hours are shown (`1:05:30`, but `5:30`)
- **Seconds** are always padded (`1:05`, not `1:5`)

Hour display is triggered when either the current value or the duration exceeds 1 hour, ensuring consistency within a Group. Remaining time displays a negative sign (customizable via the `negativeSign` prop).

Use `toggle` to let current displays switch between elapsed and remaining time, or remaining and duration displays switch between those two values. The initial display comes from `type`.

Before the media reports a duration or seekable range — while metadata is still loading, for example — no time value is available. A plain display still renders the formatted zero value but sets `data-unavailable`; a toggleable display is disabled instead: it sets `data-disabled`, leaves the tab order, and ignores activation until a value arrives.

```tsx
<Time.Value toggle />
<Time.Value toggle type="remaining" />
<Time.Value toggle type="duration" />
```

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-type` | `current` / `duration` / `remaining` | The type of time being displayed |
| `data-disabled` | Present / absent | Present when a toggleable display has no time value yet |
| `data-unavailable` | Present / absent | Present when a plain display has no time value yet |

The negative sign is rendered inside `<span aria-hidden="true">` and can be hidden with CSS:

```css
[data-type="remaining"] > span[aria-hidden] {
  display: none;
}
```

Dim a display while its value is unavailable:

```css
[data-disabled],
[data-unavailable] {
  opacity: 0.5;
}
```

## Accessibility

Each `<Time.Value>` has:

- a native `<time datetime>` element for machine-readable time semantics
- `aria-label` for the static role label (“Current time”, “Duration”, “Remaining”)

No `aria-live` region is used — time updates too frequently and might overwhelm screen readers. The separator and negative sign are `aria-hidden="true"` because the accessible label already describes the value.

Toggleable time displays receive `role="button"`, `tabindex="0"`, and keyboard support for Enter and Space. Their `aria-label` starts with the action and includes the current value. Their `aria-description` explains which values the control toggles between.

While no time value is available, a toggleable display is disabled: it sets `aria-disabled="true"` and `tabindex="-1"`, drops the `aria-description`, changes its `aria-label` to “Media not loaded, unknown time.”, and ignores clicks and key presses. A plain display in the same state omits `datetime` and uses that same label.

## Examples

### Current Time

**App.tsx**

```tsx
import { Container, createPlayer, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function CurrentTime() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <Time.Value type="current" className="media-time" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-time {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  font-variant-numeric: tabular-nums;
  color: black;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

### Current / Duration

**App.tsx**

```tsx
import { Container, createPlayer, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function CurrentDuration() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <Time.Group className="time-group">
          <Time.Value type="current" />
          <Time.Separator />
          <Time.Value type="duration" />
        </Time.Group>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.time-group {
  position: absolute;
  bottom: 10px;
  left: 10px;
  display: flex;
  gap: 4px;
  align-items: center;
  padding-block: 8px;
  padding-inline: 20px;
  font-variant-numeric: tabular-nums;
  color: black;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

### Remaining

**App.tsx**

```tsx
import { Container, createPlayer, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function Remaining() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <Time.Value type="remaining" className="media-time" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-time {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  font-variant-numeric: tabular-nums;
  color: black;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

### Custom Separator

**App.tsx**

```tsx
import { Container, createPlayer, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function CustomSeparator() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <Time.Group className="time-group">
          <Time.Value type="current" />
          <Time.Separator> of </Time.Separator>
          <Time.Value type="duration" />
        </Time.Group>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.time-group {
  position: absolute;
  bottom: 10px;
  left: 10px;
  display: flex;
  gap: 4px;
  align-items: center;
  padding-block: 8px;
  padding-inline: 20px;
  font-variant-numeric: tabular-nums;
  color: black;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

### Custom Negative Sign

**App.tsx**

```tsx
import { Container, createPlayer, Time } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function CustomNegativeSign() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <Time.Value type="remaining" negativeSign="~" className="media-time" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-time {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  font-variant-numeric: tabular-nums;
  color: black;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Value

Displays a formatted time value (current, duration, or remaining).

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `{ key: string; text: string } \| string \| ((state: TimeState) => Text \| string)` | `''` | Custom label for accessibility. |
| `negativeSign` | `string` | `'-'` | Symbol prepended to remaining time. |
| `toggle` | `boolean` | `false` | Whether the time display can be toggled. |
| `type` | `'current' \| 'duration' \| 'remaining'` | `'current'` | Which time value to display. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `type` | `'current' \| 'duration' \| 'remaining'` | Time display type. |
| `disabled` | `boolean` | Whether the time toggle is disabled. |
| `unavailable` | `boolean` | Whether the non-interactive time value is unavailable. |
| `seconds` | `number` | Raw value in seconds. |
| `negative` | `boolean` | Whether the time value is negative (remaining time before end). |
| `text` | `string` | Formatted display text without sign (e.g., "1:30"). |
| `phrase` | `string` | Human-readable phrase (e.g., "1 minute, 30 seconds"). |
| `datetime` | `string` | ISO 8601 duration (e.g., "PT1M30S"). |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-type` | `'current' \| 'duration' \| 'remaining'` | The type of time being displayed. |
| `data-disabled` | — | Present when the time toggle is disabled. |
| `data-unavailable` | — | Present when the non-interactive time value is unavailable. |

### Group

Container for composed time displays. Renders a `<span>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Time value components to render inside the group. |
| `className` | `string \| ((state: Record<string, never>) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: Record<string, never>) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: Record<string, never>) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Separator

Divider between time values. Hidden from screen readers.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | Separator content. Defaults to "/". |
| `className` | `string \| ((state: Record<string, never>) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: Record<string, never>) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: Record<string, never>) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/title -->

# Title

Displays the resolved content title for the current media

## Import

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

## Anatomy

```tsx
<Title />
```

## Behavior

The component renders the resolved title directly as text and owns that text: it does not accept `children`. Set the title on the player instead.

```tsx
<Player title="Big Buck Bunny">
  <Container>
    <Video src="video.mp4" />
    <Title />
  </Container>
</Player>
```

A title can come from two places. The player uses the first one that has a value:

1. The title you set on the player.
2. The title the media reports about itself.

If neither has a value, there is nothing to show and the title hides itself.

The title is player input, not player state, so change it the way you set it in the first place. The store exposes the resolved `title` to read, and nothing to write. That resolution belongs to the [metadata feature](https://videojs.org/docs/framework/react/reference/api/feature-metadata), which the video and audio presets include.

```tsx
const [title, setTitle] = useState("Big Buck Bunny");

<Player title={title}>...</Player>;
```

Set it to `null` to hand the title back to the media.

The component exposes `data-visible` while controls are visible. Use that hook to animate the title with the controls.

## Styling

React renders a `<div>`, or nothing at all when no title resolves. Add a `className` to style it:

```css
.title {
  opacity: 0;
  transition: opacity 150ms ease-out;
}
```

To fade the title in and out with the controls, use the root’s `data-visible` attribute:

```css
.title[data-visible] {
  opacity: 1;
}
```

`className` and `style` also accept a function of component state when you would rather branch in JavaScript than in CSS:

```tsx
<Title className={(state) => (state.title.length > 40 ? "title title--long" : "title")} />
```

## Accessibility

The title is ordinary text, so it reaches assistive technology as content with no ARIA of its own. The native `hidden` attribute it sets when there is no title also removes it from the accessibility tree, so nothing is announced when there is nothing to announce.

Fading the title out with `opacity` leaves it readable by a screen reader while it is not painted. That is deliberate — the name of what is playing stays relevant whether or not the controls happen to be on screen.

The component does not name the player. To give the player region an accessible name, set `aria-label` or `aria-labelledby` on the container yourself.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, PlayButton, Title } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player title="Big Buck Bunny">
      <Container className="react-title-basic">
        <Video loop muted playsInline src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" />
        <Title className="react-title-basic__title" />
        <PlayButton
          className="react-title-basic__button"
          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-title-basic {
  position: relative;
  display: block;
}

.react-title-basic video {
  display: block;
  width: 100%;
}

/* React renders nothing until a title resolves, so the gradient never sits
   over empty space without this demo doing anything. */
.react-title-basic__title {
  position: absolute;
  inset-inline: 0;
  top: 0;
  padding: 16px 20px 48px;
  font-size: 16px;
  font-weight: 500;
  color: white;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.5);
  pointer-events: none;
  background: linear-gradient(to bottom, rgba(0, 0, 0, 0.7), transparent);
}

.react-title-basic__button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 20px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `title` | `string` | The resolved content title. Empty when no source supplied one. |
| `hidden` | `boolean` | Whether the component is hidden because no title is available. |
| `visible` | `boolean` | Whether the player controls are visible. |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-hidden` | Present when the element is hidden because no title is available. |
| `data-visible` | Present while the player controls are visible. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/poster -->

# Poster

Poster image component that displays a thumbnail until video playback starts

## Import

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

## Anatomy

```tsx
<Poster.Root>
  <Poster.Image />
</Poster.Root>
```

## Behavior

The poster shows before playback starts. Once the user plays or seeks, it hides; pausing does not bring it back. Loading a new source shows it again.

You can set the poster URL on the player. This is useful when you want to change the poster from inside a skin, or keep all your media metadata in one place:

```tsx
<VideoPlayer poster="poster.jpg" />
```

## Supply your own image

The component fills in a source only when you leave one out. `srcset`, `sizes`, `loading`, `<picture>`, and framework image components all stay available.

`Poster.Root` owns visibility and loading state. Image attributes go on `Poster.Image`:

```tsx
<Poster.Root>
  <Poster.Image srcSet="poster-480.jpg 480w, poster-1080.jpg 1080w" sizes="100vw" />
</Poster.Root>
```

To render a different image component, use `render` on `Poster.Image`. It receives the poster URL as `src`, undefined until one resolves:

```tsx
<Poster.Root>
  <Poster.Image
    render={({ src, ...props }: ComponentProps<'img'>) =>
      src ? <Image {...props} src={src} alt="" fill /> : null
    }
  />
</Poster.Root>
```

Inside a skin, pass the same function as `renderPoster`. The skin draws your image in place of its own:

```tsx
<VideoSkin
  renderPoster={({ src, ...props }: ComponentProps<'img'>) =>
    src ? <Image {...props} src={src} alt="" fill /> : null
  }
/>
```

A skin styles the `<img>` it draws directly. Render something that is not an `<img>` and its sizing is yours.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-visible` | Present / absent | Present before playback starts |
| `data-loading` | Present / absent | Present while the image is fetching |
| `data-loaded` | Present / absent | Present once the image has loaded |
| `data-error` | Present / absent | Present when the image failed |

The three load attributes track the image on screen, including one you supplied yourself.

React renders a root `<div>` around the `<img>`. The state attributes are on `Poster.Root`, so other presentation layers can use the same lifecycle:

```tsx
<Poster.Root className="media-poster">
  <img className="media-poster-blur" src={blurDataURL} alt="" aria-hidden />
  <Poster.Image className="media-poster-image" />
  <div className="media-poster-overlay" aria-hidden />
</Poster.Root>
```

```css
.media-poster:not([data-visible]) {
  opacity: 0;
}

.media-poster:not([data-loading]) .media-poster-blur {
  opacity: 0;
}
```

## Accessibility

Unlike the native `<video poster>` attribute, this component lets you describe the poster for screen readers.

The image is decorative by default (`alt=""`), since a URL says nothing about what the image shows. When the poster carries meaning, say so:

```tsx
<Poster.Root>
  <Poster.Image alt="Keynote speaker at a conference" />
</Poster.Root>
```

Whether a poster is informative or decorative is your judgment, per the [WAI guidelines](https://www.w3.org/WAI/tutorials/images/decorative/).

## Examples

### Basic Usage

**App.tsx**

```tsx
import { Container, createPlayer, PlayButton, Poster } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsInline />

        <Poster.Root className="media-poster">
          <Poster.Image className="media-poster-image" />
        </Poster.Root>

        <PlayButton
          className="media-play-button"
          render={(props, state) => <button {...props}>{state.paused ? 'Play' : 'Pause'}</button>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
}

.media-container video {
  width: 100%;
}

.media-poster {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  pointer-events: none;
  transition: opacity 0.25s;
}

.media-poster:not([data-visible]) {
  opacity: 0;
}

.media-poster-image {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.media-play-button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding-block: 8px;
  padding-inline: 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.75);
  border: 1px solid rgba(255, 255, 255, 0.25);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}
```

## API Reference

### Root

Manages poster visibility and image loading state.

Renders a `div` and exposes `data-visible`, `data-loading`, `data-loaded`, and `data-error` for styling every layer in the poster presentation. Render `Poster.Image` inside it for the image that supplies the loading lifecycle.

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | Whether the poster should be shown, which it is until playback starts. |
| `src` | `string` | Resolved poster URL, empty when nothing supplied one. |
| `loading` | `boolean` | Whether the poster image is fetching. |
| `loaded` | `boolean` | Whether the poster image has decoded. |
| `error` | `boolean` | Whether the poster image failed. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present until playback starts. |
| `data-loading` | Present while the poster image is fetching. |
| `data-loaded` | Present once the poster image has decoded. |
| `data-error` | Present when the poster image failed. |

### Image

Displays the poster image managed by `Poster.Root`.

Renders an `img`, so `srcSet`, `sizes`, `loading`, and the rest of the native image attributes remain available. Leave the source off and the player's resolved poster fills it in. The image is decorative unless you supply `alt`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: PosterState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: PosterState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: PosterState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/thumbnail -->

# Thumbnail

Time-based thumbnail preview component for timeline scrubbing and hover previews

## Quick Start: Video Track

`Thumbnail` can read thumbnail cues directly from your video track. Add a `<track>` with `kind="metadata"` and `label="thumbnails"` to your media component.

[Mux](https://www.mux.com/?utm_source=videojs&utm_campaign=vjs10&utm_content=docs-content) provides this as `storyboard.vtt`:

`https://image.mux.com/{PLAYBACK_ID}/storyboard.vtt`

That track is cross-origin, and a cross-origin `<track>` only loads when the media component is CORS-enabled:

```tsx
<Video src="video.mp4" crossOrigin="anonymous">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
    default
  />
</Video>
<Thumbnail.Root time={12}>
  <Thumbnail.Image />
</Thumbnail.Root>
```

A same-origin track needs none of this.

## Import

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

## Anatomy

```tsx
<Thumbnail.Root>
  <Thumbnail.Image />
</Thumbnail.Root>
```

## Behavior

The thumbnail root resolves an image for the current `time`, owns `src` and `srcset` on it, and reports its loading lifecycle.

Render that image with `Thumbnail.Image`.

Supported source formats:

- Text track: `<track kind="metadata" label="thumbnails" src="...vtt">`
- JSON array: `{ url, startTime, endTime? }[]`
- JSON sprite array: `{ url, startTime, endTime?, width, height, coords }[]`

Text-track mode needs `Player` because it reads track state from the player store. JSON modes (`thumbnails` prop) work without a player.

The component picks the latest thumbnail whose `startTime` is less than or equal to the current `time`, then scales/clips sprite tiles to fill CSS min/max constraints while preserving aspect ratio. Tiles scale up as well as down, so a preview whose `max-width` grows — a container query widening it in fullscreen, say — grows with it.

### Cross-origin images

Leave `crossOrigin` unset and the thumbnail follows the media component. A cross-origin thumbnail `<track>` only loads when the media is CORS-enabled, so the images its cues point at are fetched with that same mode. Skins get this for free, with nothing to thread through.

Opt out to fetch them without CORS:

```tsx
<Thumbnail.Root time={12}>
  <Thumbnail.Image crossOrigin={null} />
</Thumbnail.Root>
```

An empty value does not opt out either. The [CORS settings attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/crossorigin) reads anything other than `use-credentials` as Anonymous, so it is a value like any other.

Thumbnails you supply through `thumbnails` never inherit, since they need not be related to the media component at all. Set `crossOrigin` yourself when those images need it.

## Styling

Use state data attributes for pure CSS styling:

React renders a root `<div>` around an `<img>`. State attributes belong to `Thumbnail.Root`, while image attributes and `render` belong to `Thumbnail.Image`:

```tsx
<Thumbnail.Root className="media-thumbnail" time={12}>
  <Thumbnail.Image className="media-thumbnail-image" loading="eager" />
  <div className="media-thumbnail-overlay" aria-hidden />
</Thumbnail.Root>
```

The root clips to the selected tile while the image inside spans the whole sprite sheet, so anything after the image in flow lands past the clip edge. Position the root and lay overlays over it:

```css
.media-thumbnail {
  position: relative;
}

.media-thumbnail-overlay {
  position: absolute;
  inset: 0;
}

.media-thumbnail[data-hidden] {
  display: none;
}

.media-thumbnail[data-loading] {
  opacity: 0.6;
}

.media-thumbnail[data-error] {
  outline: 1px solid #ef4444;
}
```

## Accessibility

`Thumbnail.Root` is decorative by default (`aria-hidden="true"`). It is intended for visual preview UX (for example, timeline hover previews) rather than primary accessible content.

## Examples

### Text Track (VTT)

**App.tsx**

```tsx
import { Container, createPlayer, Thumbnail } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function TextTrackUsage() {
  return (
    <Player>
      <Container className="demo">
        <Video
          className="media"
          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
          preload="auto"
          muted
          playsInline
          crossOrigin="anonymous"
        >
          <track kind="metadata" label="thumbnails" src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt" default />
        </Video>
        <Thumbnail.Root className="media-thumbnail" time={12}>
          <Thumbnail.Image className="media-thumbnail-image" />
        </Thumbnail.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.demo {
  position: relative;
  max-width: 280px;
}

.media {
  position: absolute;
  width: 1px;
  height: 1px;
  pointer-events: none;
  opacity: 0;
}

.media-thumbnail {
  display: block;
  width: auto;
  min-width: 0;
  max-width: 240px;
}

.media-thumbnail-image {
  display: block;
}

.media-thumbnail[data-hidden] {
  display: none;
}
```

### JSON Array

**App.tsx**

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

const THUMBNAILS = [
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=0',
    startTime: 0,
    endTime: 10,
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=10',
    startTime: 10,
    endTime: 20,
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg?time=20',
    startTime: 20,
  },
];

export default function JsonUsage() {
  return (
    <Thumbnail.Root thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }}>
      <Thumbnail.Image />
    </Thumbnail.Root>
  );
}
```

### JSON Sprite Array

**App.tsx**

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

const THUMBNAILS = [
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 0,
    endTime: 10,
    width: 284,
    height: 160,
    coords: { x: 0, y: 0 },
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 10,
    endTime: 20,
    width: 284,
    height: 160,
    coords: { x: 284, y: 0 },
  },
  {
    url: 'https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.jpg',
    startTime: 20,
    width: 284,
    height: 160,
    coords: { x: 568, y: 0 },
  },
];

export default function JsonSpriteUsage() {
  return (
    <Thumbnail.Root thumbnails={THUMBNAILS} time={12} style={{ maxWidth: 240 }}>
      <Thumbnail.Image />
    </Thumbnail.Root>
  );
}
```

## API Reference

### Root

Resolves, sizes, and clips a thumbnail for a point in time.

Renders a `div` and exposes `data-hidden`, `data-loading`, and `data-error` for styling every layer in the preview. Render `Thumbnail.Image` inside it for the image the root controls and measures.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `thumbnails` | `ThumbnailImage[]` | — | Pre-parsed thumbnail images — bypasses the automatic `<track>` detection. |
| `time` | `number` | — | Time in seconds to display the thumbnail for. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `loading` | `boolean` | The thumbnail image is loading. |
| `error` | `boolean` | The thumbnail image failed to load. |
| `hidden` | `boolean` | Whether the component is hidden because no thumbnail is available and it is not loading. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-loading` | |
| `data-error` | |
| `data-hidden` | |

### Image

Displays the image selected and measured by `Thumbnail.Root`.

Renders an `img`, so native image attributes and the `render` escape hatch remain available without replacing the root that owns thumbnail state.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: ThumbnailState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `crossOrigin` | `ThumbnailCrossOrigin` | — | CORS setting for the selected image. Leave unset to follow the media component, or pass `null` to opt out. |
| `fetchPriority` | `ThumbnailFetchPriority` | — | Image fetch priority hint. |
| `loading` | `ThumbnailLoading` | — | Image loading strategy. |
| `render` | `ReactElement \| ((props: HTMLProps, state: ThumbnailState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: ThumbnailState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/tooltip -->

# Tooltip

A tooltip component for displaying contextual labels on hover and focus

## Import

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

## Anatomy

```tsx
<Tooltip.Provider>
  <Tooltip.Root>
    <Tooltip.Trigger>Hover me</Tooltip.Trigger>
    <Tooltip.Popup>
      <Tooltip.Arrow />
      <Tooltip.Label>Label text</Tooltip.Label>
      <Tooltip.Shortcut>K</Tooltip.Shortcut>
    </Tooltip.Popup>
  </Tooltip.Root>
</Tooltip.Provider>
```

## Behavior

Displays a short label anchored to a trigger element. Opens after a configurable `delay` (default 600ms) on hover or immediately on focus. Closes when the pointer leaves or focus moves away, with an optional `closeDelay`.

The `side` and `align` props control the preferred placement relative to the trigger. When the preferred side overflows the positioning boundary, the tooltip uses the opposite side if it has more space. Positioning uses CSS Anchor Positioning where supported, with a JavaScript measurement fallback.

The component is composed from six parts: `Root` manages state and context, `Trigger` renders a button that activates the tooltip, `Popup` contains the label content, `Label` renders the tooltip body, `Shortcut` renders an optional keyboard hint, and `Arrow` renders a decorative pointer. Wrap multiple tooltips in a `Tooltip.Provider` to coordinate open/close timing across a group — once a tooltip becomes visible, adjacent tooltips open instantly within the `timeout` window, skipping the normal `delay`.

Tooltips inside a [player container](https://videojs.org/docs/framework/react/reference/components/player-container) also observe its popup group. By default, a tooltip does not open—or closes if already open—while a menu or popover attached to the same trigger is open. Set `sticky` when the tooltip should remain visible with that trigger’s popup.

`Tooltip.Provider` coordinates tooltip delay timing only; it does not replace the container’s popup group.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/react/reference/components/tooltip#root-css-custom-properties) for positioning offsets:

React renders standard DOM elements. Add a `className` to style them:

```css
.tooltip-popup {
  --media-tooltip-side-offset: 8px;
  --media-tooltip-align-offset: 0px;
  --media-tooltip-boundary-offset: 8px;
}
```

Style based on open state, rendered side, and transition phases. `data-side` reflects the rendered side and can differ from the preferred `side` prop after collision handling:

```css
.tooltip-popup[data-open] {
  display: block;
}
.tooltip-popup[data-starting-style] {
  opacity: 0;
}
.tooltip-popup[data-ending-style] {
  opacity: 0;
}
.tooltip-popup[data-side="top"] {
  transform-origin: bottom center;
}
.tooltip-popup[data-side="bottom"] {
  transform-origin: top center;
}
```

## Accessibility

Tooltips are visual-only, supplementary labels. The popup renders with `role="presentation"` and is not referenced by the trigger with `aria-describedby`. Give the trigger its own accessible name instead of relying on tooltip content. Built-in media buttons already expose a state-aware `aria-label`, and their tooltips reuse that translated label. Tooltips still open on focus so keyboard users who can see the label receive the same visual hint.

## Examples

### Basic Usage

**App.tsx**

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

export default function BasicUsage() {
  return (
    <div className="demo">
      <Tooltip.Root>
        <Tooltip.Trigger className="trigger">Hover me</Tooltip.Trigger>
        <Tooltip.Popup className="media-tooltip">
          <Tooltip.Arrow className="arrow" />
          <Tooltip.Label>Tooltip content</Tooltip.Label>
        </Tooltip.Popup>
      </Tooltip.Root>
    </div>
  );
}
```

**App.css**

```css
.demo {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 40px 24px;
}

.trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  border-radius: 9999px;
  backdrop-filter: blur(10px);
}

.media-tooltip {
  --media-tooltip-side-offset: 8px;
  padding: 4px 10px;
  margin: 0;
  font-size: 13px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.85);
  border: 0;
  border-radius: 6px;
  backdrop-filter: blur(10px);
}

.arrow {
  fill: rgba(0, 0, 0, 0.85);
}
```

### Grouping

Wrap multiple tooltips in a `Tooltip.Provider` to share a delay group. Once a tooltip becomes visible, adjacent tooltips open instantly within the `timeout` window, skipping the normal `delay`.

**App.tsx**

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

export default function Grouping() {
  return (
    <div className="demo">
      <Tooltip.Provider>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Play</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Play video</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Mute</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Mute audio</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
        <Tooltip.Root>
          <Tooltip.Trigger className="trigger">Fullscreen</Tooltip.Trigger>
          <Tooltip.Popup className="media-tooltip">
            <Tooltip.Arrow className="arrow" />
            <Tooltip.Label>Enter fullscreen</Tooltip.Label>
          </Tooltip.Popup>
        </Tooltip.Root>
      </Tooltip.Provider>
    </div>
  );
}
```

**App.css**

```css
.demo {
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 40px 24px;
}

.trigger {
  padding: 6px 16px;
  color: black;
  cursor: pointer;
  background: rgba(255, 255, 255, 0.7);
  border: 1px solid rgba(255, 255, 255, 0.3);
  backdrop-filter: blur(10px);
}

.media-tooltip {
  --media-tooltip-side-offset: 8px;
  padding: 4px 10px;
  margin: 0;
  font-size: 13px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.85);
  border: 0;
  border-radius: 6px;
  backdrop-filter: blur(10px);
}

.arrow {
  fill: rgba(0, 0, 0, 0.85);
}
```

## API Reference

### Provider

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | — | Default close delay in ms for tooltips in this group. |
| `delay` | `number` | — | Default open delay in ms for tooltips in this group. |
| `timeout` | `number` | — | Duration in ms after a tooltip closes during which the next tooltip opens instantly. |

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment of the tooltip along the trigger's edge. |
| `boundary` | `'viewport' \| 'container' \| string & {}` | — | Boundary used to constrain the tooltip position. |
| `closeDelay` | `number` | `0` | Delay in ms before closing after pointer leaves. |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
| `delay` | `number` | `600` | Delay in ms before opening on hover. |
| `disabled` | `boolean` | `false` | When true, the tooltip is disabled and will not open. |
| `disableHoverablePopup` | `boolean` | `true` | When true, hovering the popup does not keep it open. |
| `open` | `boolean` | `false` | Controlled open state. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Preferred side of the trigger for the tooltip. |
| `sticky` | `boolean` | `false` | Whether the tooltip stays open when another popup opens from its trigger. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the tooltip is currently visible. |
| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Preferred side of the trigger for the tooltip. |
| `align` | `'start' \| 'center' \| 'end'` | How the tooltip is aligned relative to the specified side. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the tooltip is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-tooltip-side-offset` | Distance between the popup and the trigger along the side axis. |
| `--media-tooltip-align-offset` | Distance between the popup and the trigger along the alignment axis. |
| `--media-tooltip-boundary-offset` | Minimum distance between the popup and the positioning boundary. |
| `--media-tooltip-anchor-width` | The anchor element's width. |
| `--media-tooltip-anchor-height` | The anchor element's height. |
| `--media-tooltip-available-width` | Available width between the trigger and the boundary edge. |
| `--media-tooltip-available-height` | Available height between the trigger and the boundary edge. |

### Trigger

Element that triggers the tooltip on hover and focus. Renders a `<button>` element.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the tooltip is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

### Popup

Container for the tooltip content. Positioned relative to the trigger using CSS anchor positioning with a JavaScript fallback.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the tooltip is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

### Label

Tooltip body label; defaults to context `content.label` from the linked trigger.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the tooltip is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

### Shortcut

Keyboard shortcut hint; apply skin `className` (CSS: `media-tooltip__kbd`; Tailwind: `popup.tooltipShortcut`).

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present when the tooltip is open. |
| `data-side` | `'top' \| 'bottom' \| 'left' \| 'right'` | Indicates the rendered side of the tooltip after collision handling. |
| `data-align` | `'start' \| 'center' \| 'end'` | Indicates how the tooltip is aligned relative to the specified side. |

### Arrow

Decorative arrow pointing from the tooltip toward the trigger. Hidden from assistive technology.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: TooltipState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: TooltipState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: TooltipState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/buffering-indicator -->

# BufferingIndicator

Loading indicator that displays when the video player is buffering or waiting for data

## Import

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

## Anatomy

```tsx
<BufferingIndicator />
```

## Behavior

Shows a loading indicator when the media is waiting to buffer and not paused, but only after a configurable `delay` (default 500ms). This delay prevents the indicator from flickering during brief stalls. The indicator hides immediately when buffering ends.

## Styling

Hide and show the indicator based on the `data-visible` attribute.

## Examples

### Basic Usage

**App.tsx**

```tsx
import { BufferingIndicator, Container, createPlayer } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="media-container">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <BufferingIndicator
          className="media-buffering-indicator"
          render={(props, state) => <div {...props}>{state.visible && <div className="spinner" />}</div>}
        />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.media-container {
  position: relative;
  display: flex;
  width: 100%;
  height: 100%;
}

.media-buffering-indicator {
  position: absolute;
  inset: 0;
  z-index: 30;
  display: flex;
  align-items: center;
  justify-content: center;
  pointer-events: none;
}

.spinner {
  display: none;
  width: 48px;
  height: 48px;
  border: 4px solid rgba(255, 255, 255, 0.3);
  border-top-color: white;
  border-radius: 50%;
  animation: buffering-spin 0.8s linear infinite;
}

.media-buffering-indicator[data-visible] .spinner {
  display: block;
}

@keyframes buffering-spin {
  to {
    transform: rotate(360deg);
  }
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `500` | Delay in milliseconds before the indicator becomes visible. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `visible` | `boolean` | Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused. |

### Data attributes

| Attribute | Description |
| --- | --- |
| `data-visible` | Present when the buffering indicator is visible (after delay). |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/seek-indicator -->

# SeekIndicator

A temporary visual indicator for keyboard and gesture seeking

## Import

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

## Anatomy

```tsx
<SeekIndicator.Root>
  <SeekIndicator.Value />
</SeekIndicator.Root>
```

## Behavior

`SeekIndicator` displays feedback for seek actions emitted by a [`Hotkey`](https://videojs.org/docs/framework/react/reference/components/hotkey) or [`Gesture`](https://videojs.org/docs/framework/react/reference/components/gesture) in the same player `Container`. It does not react to current-time changes or seek commands invoked directly through the player store.

| Action | Direction | Value |
| --- | --- | --- |
| `seekStep` | The sign of `value` determines `forward` or `backward` | The absolute number of seconds, such as `10s` |
| `seekToPercent` | The target percentage is compared with the current time | The formatted current time when the action occurred |

Rapid `seekStep` actions in the same direction accumulate while the indicator is open. For example, two 10-second forward actions display `20s`. Changing direction or using `seekToPercent` starts a new display. During a rapid sequence, another full step is not added when it would pass the start or duration boundary.

For `seekToPercent`, pass a percentage from 0 to 100 as `value`. A `Hotkey` with `keys="0-9"` can omit `value`; the pressed digit maps to 0%, 10%, and so on through 90%.

The indicator closes after `closeDelay`, which defaults to 800 milliseconds.

`SeekIndicator.Root` stops rendering after its close transition.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-open` | Present / absent | Present while the indicator is open |
| `data-direction` | `"forward"` \| `"backward"` | Direction of the handled seek |
| `data-starting-style` | Present / absent | Present during the open transition |
| `data-ending-style` | Present / absent | Present during the close transition |

Position the root from `data-direction` and use the transition attributes for entry and exit styles.

React renders standard DOM elements. Add a `className` to the Root:

```css
.seek-indicator[data-direction="backward"] {
  left: 1rem;
}

.seek-indicator[data-direction="forward"] {
  right: 1rem;
}

.seek-indicator[data-starting-style],
.seek-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`SeekIndicator` is visual feedback and does not create a live region. Keep the same seek operation available through keyboard-operable controls, and pair it with [`StatusAnnouncer`](https://videojs.org/docs/framework/react/reference/components/status-announcer) when changes should be announced to screen readers. Do not make `SeekIndicator.Value` a live region because rapid seek input would produce repeated announcements.

## Examples

### Basic Usage

Focus the player, then press the left or right arrow key to seek by ten seconds. Press a digit from 0 through 9 to seek to a percentage of the duration.

**App.tsx**

```tsx
import { Container, createPlayer, Hotkey, SeekIndicator } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-seek-indicator-basic" tabIndex={0}>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop />
        <p className="react-seek-indicator-basic__instructions">
          Focus the player · ←/→: seek 10s · 0–9: seek to percent
        </p>
        <SeekIndicator.Root className="react-seek-indicator-basic__indicator" aria-hidden="true">
          <SeekIndicator.Value className="react-seek-indicator-basic__value" />
        </SeekIndicator.Root>
        <Hotkey keys="ArrowLeft" action="seekStep" value={-10} />
        <Hotkey keys="ArrowRight" action="seekStep" value={10} />
        <Hotkey keys="0-9" action="seekToPercent" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-seek-indicator-basic {
  position: relative;
}

.react-seek-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.react-seek-indicator-basic video {
  display: block;
  width: 100%;
}

.react-seek-indicator-basic__instructions {
  position: absolute;
  top: 10px;
  left: 50%;
  padding: 6px 10px;
  margin: 0;
  color: white;
  text-align: center;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
  translate: -50%;
}

.react-seek-indicator-basic__indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  display: grid;
  min-width: 72px;
  padding: 16px;
  color: white;
  pointer-events: none;
  background: rgb(0 0 0 / 72%);
  border-radius: 9999px;
  place-items: center;
  transform: translate(-50%, -50%);
  transition:
    opacity 160ms ease-in-out,
    scale 160ms ease-in-out;
}

.react-seek-indicator-basic__indicator::before {
  font-size: 24px;
  line-height: 1;
  content: "↔";
}

.react-seek-indicator-basic__indicator[data-direction="backward"] {
  right: auto;
  left: 16px;
  transform: translateY(-50%);
}

.react-seek-indicator-basic__indicator[data-direction="backward"]::before {
  content: "↶";
}

.react-seek-indicator-basic__indicator[data-direction="forward"] {
  right: 16px;
  left: auto;
  transform: translateY(-50%);
}

.react-seek-indicator-basic__indicator[data-direction="forward"]::before {
  content: "↷";
}

.react-seek-indicator-basic__indicator[data-starting-style],
.react-seek-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

.react-seek-indicator-basic__value {
  font-variant-numeric: tabular-nums;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | — | Delay in milliseconds before the indicator closes. |
| `locale` | `string \| string[]` | — | |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the indicator is open. |
| `generation` | `number` | Increments each time a seek input action updates the indicator. |
| `direction` | `'forward' \| 'backward' \| null` | Direction of the seek, or `null` when the target does not change the current time. |
| `count` | `number` | Number of same-direction seek steps accumulated in the current display. |
| `seekTotal` | `number` | Absolute number of seconds accumulated from seek-step actions. |
| `value` | `string \| null` | Accumulated seek-step label, or `null` for percentage seeks. |
| `currentTime` | `string` | Formatted current time captured when the input action occurred. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present while the indicator is open. |
| `data-direction` | `'forward' \| 'backward' \| null` | Direction of the seek as `"forward"` or `"backward"`. |
| `data-starting-style` | — | Present during the open transition. |
| `data-ending-style` | — | Present during the close transition. |

### Value

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: SeekIndicatorState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: SeekIndicatorState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: SeekIndicatorState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/status-indicator -->

# StatusIndicator

Display temporary visual feedback for keyboard and gesture actions

## Import

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

## Anatomy

```tsx
<StatusIndicator.Root>
  <StatusIndicator.Value />
</StatusIndicator.Root>
```

## Behavior

`StatusIndicator` displays feedback for actions emitted by a [`Hotkey`](https://videojs.org/docs/framework/react/reference/components/hotkey) or [`Gesture`](https://videojs.org/docs/framework/react/reference/components/gesture) in the same player `Container`. It does not react to buttons, direct player-store changes, or media state changes on their own.

The input event arrives before its action is resolved. The indicator uses the media snapshot from that moment to predict the next visual status:

| Action | `data-status` | Value |
| --- | --- | --- |
| `togglePaused` | `"play"` or `"pause"` | Translated playing or paused label |
| `toggleMuted` | `"volume-off"`, `"volume-low"`, or `"volume-high"` | Predicted volume percentage |
| `volumeStep` | `"volume-off"`, `"volume-low"`, or `"volume-high"` | Predicted volume percentage |
| `toggleSubtitles` | `"captions-on"` or `"captions-off"` | Translated captions label |
| `toggleFullscreen` | `"fullscreen"` or `"exit-fullscreen"` | Translated fullscreen label |
| `togglePictureInPicture` | `"pip"` or `"exit-pip"` | Translated picture-in-picture label |

`toggleSubtitles` is ignored when the player reports that no captions or subtitles are available. Seek actions, `toggleControls`, playback-rate actions, and custom actions do not open this indicator unless you [derive a custom status](https://videojs.org/docs/framework/react/reference/components/status-indicator#custom-actions).

Use `actions` to allow only some of the supported actions. Omitting it allows all supported actions.

Pass a readonly array of action names:

```tsx
<StatusIndicator.Root actions={["togglePaused", "toggleMuted"]}>
  <StatusIndicator.Value />
</StatusIndicator.Root>
```

The indicator closes after `closeDelay`, which defaults to 800 milliseconds. A repeated handled action updates the current value and restarts that close timer without replaying the entry transition.

`StatusIndicator.Root` stops rendering after its close transition.

## Custom actions

Use `deriveCustomStatus` to give custom hotkey or gesture actions the same feedback as built-in actions. The indicator calls it only when an allowed action has no built-in status. It receives the input event and the pre-action media snapshot. Return `{ status, label, value }` to open the indicator, or `null` to leave it closed. The returned `status` becomes `data-status`, and the Value part shows `value` when it is not `null` and `label` otherwise. Because the snapshot is taken before the action runs, predict the post-action state the way built-in statuses do.

Register the custom action with [`useHotkey`](https://videojs.org/docs/framework/react/reference/api/use-hotkey) and pass `action` so the indicator receives it. `Hotkey` only accepts built-in actions.

```tsx
import { selectPlaybackRate, StatusIndicator, useHotkey, usePlayer } from "@videojs/react";

const rates = [0.5, 1, 1.5, 2];

function getNextRate(rate = 1) {
  const index = rates.indexOf(rate);

  return rates[Math.min(index + 1, rates.length - 1)] ?? rate;
}

function RateHotkey() {
  const rate = usePlayer(selectPlaybackRate);

  useHotkey({
    keys: ">",
    action: "stepRate",
    onActivate: () => rate?.setPlaybackRate(getNextRate(rate.playbackRate)),
  });

  // The hook must run inside a component, but this one has no UI to render.
  return null;
}

function RateIndicator() {
  return (
    <StatusIndicator.Root
      actions={["stepRate"]}
      deriveCustomStatus={(event, snapshot) =>
        event.action === "stepRate"
          ? { status: "rate-up", label: `${getNextRate(snapshot.playbackRate)}×`, value: null }
          : null
      }
    >
      <StatusIndicator.Value />
    </StatusIndicator.Root>
  );
}
```

Render both components inside the same player `Container`.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-open` | Present / absent | Present while the indicator is open |
| `data-status` | `"play"`, `"pause"`, `"volume-off"`, `"volume-low"`, `"volume-high"`, `"captions-on"`, `"captions-off"`, `"fullscreen"`, `"exit-fullscreen"`, `"pip"`, `"exit-pip"`, or a custom status | Predicted status for the handled action |
| `data-starting-style` | Present / absent | Present during the open transition |
| `data-ending-style` | Present / absent | Present during the close transition |

Use `data-status` to select an icon or other visual treatment, and use the transition attributes for entry and exit styles.

React renders standard DOM elements. Add a `className` to the Root:

```css
.status-indicator[data-status="play"] {
  color: green;
}

.status-indicator[data-starting-style],
.status-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`StatusIndicator` is visual feedback and does not create a live region. Keep every action available through keyboard-operable controls, and pair the player with [`StatusAnnouncer`](https://videojs.org/docs/framework/react/reference/components/status-announcer) when state changes should be announced to screen readers. Do not make `StatusIndicator.Value` a live region.

## Examples

### Basic Usage

Focus the player, then press K to play or pause, M to mute, F for fullscreen, C for captions, or I for picture-in-picture.

**App.tsx**

```tsx
import { Container, createPlayer, Hotkey, StatusIndicator } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

const statusActions = [
  'togglePaused',
  'toggleMuted',
  'toggleSubtitles',
  'toggleFullscreen',
  'togglePictureInPicture',
] as const;

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-status-indicator-basic" tabIndex={0}>
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoPlay muted playsInline loop>
          <track kind="captions" src="/docs/demos/captions-button/captions.vtt" srcLang="en" label="English" />
        </Video>
        <p className="react-status-indicator-basic__instructions">
          Focus the player · K: play/pause · M: mute · F: fullscreen · C: captions · I: picture-in-picture
        </p>
        <StatusIndicator.Root
          className="react-status-indicator-basic__indicator"
          actions={statusActions}
          aria-hidden="true"
        >
          <StatusIndicator.Value className="react-status-indicator-basic__value" />
        </StatusIndicator.Root>
        <Hotkey keys="k" action="togglePaused" />
        <Hotkey keys="m" action="toggleMuted" />
        <Hotkey keys="f" action="toggleFullscreen" />
        <Hotkey keys="c" action="toggleSubtitles" />
        <Hotkey keys="i" action="togglePictureInPicture" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-status-indicator-basic {
  position: relative;
}

.react-status-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.react-status-indicator-basic video {
  display: block;
  width: 100%;
}

.react-status-indicator-basic__instructions {
  position: absolute;
  top: 10px;
  right: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  text-align: center;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.react-status-indicator-basic__indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  display: grid;
  min-width: 92px;
  padding: 16px;
  color: white;
  pointer-events: none;
  background: rgb(0 0 0 / 72%);
  border-radius: 12px;
  place-items: center;
  transform: translate(-50%, -50%);
  transition:
    opacity 160ms ease-in-out,
    scale 160ms ease-in-out;
}

.react-status-indicator-basic__indicator::before {
  font-size: 28px;
  font-weight: 700;
  line-height: 1;
}

.react-status-indicator-basic__indicator[data-status="play"]::before {
  content: "▶";
}

.react-status-indicator-basic__indicator[data-status="pause"]::before {
  content: "Ⅱ";
}

.react-status-indicator-basic__indicator[data-status="volume-off"]::before {
  content: "🔇";
}

.react-status-indicator-basic__indicator[data-status="volume-low"]::before {
  content: "🔉";
}

.react-status-indicator-basic__indicator[data-status="volume-high"]::before {
  content: "🔊";
}

.react-status-indicator-basic__indicator[data-status="captions-on"]::before,
.react-status-indicator-basic__indicator[data-status="captions-off"]::before {
  content: "CC";
}

.react-status-indicator-basic__indicator[data-status="captions-off"]::before {
  text-decoration: line-through;
}

.react-status-indicator-basic__indicator[data-status="fullscreen"]::before {
  content: "⛶";
}

.react-status-indicator-basic__indicator[data-status="exit-fullscreen"]::before {
  content: "⊠";
}

.react-status-indicator-basic__indicator[data-status="pip"]::before,
.react-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  content: "▣";
}

.react-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  text-decoration: line-through;
}

.react-status-indicator-basic__indicator[data-starting-style],
.react-status-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

.react-status-indicator-basic__value {
  margin-top: 8px;
  font-variant-numeric: tabular-nums;
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `readonly InputAction[]` | — | Input actions allowed to open the indicator. All supported actions are allowed when omitted. |
| `closeDelay` | `number` | — | Delay in milliseconds before the indicator closes. |
| `deriveCustomStatus` | `((event: InputActionEvent, snapshot: MediaSnapshot) => StatusDetails<IndicatorStatus> \| null)` | — | Derives display details for custom actions. Called only when the built-in derivation returns `null`; return `null` to leave the indicator closed. |
| `labels` | `Partial<InputIndicatorLabels>` | — | Internal translated label overrides supplied by framework adapters. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the indicator is open. |
| `generation` | `number` | Increments each time a supported input action updates the indicator. |
| `status` | `'pause' \| 'play' \| 'volume-off' \| 'volume-low' \| 'volume-high' \| 'captions-on' \| 'captions-off' \| 'fullscreen' \| 'exit-fullscreen' \| 'pip' \| 'exit-pip' \| string & {} \| null` | Visual status for the handled input action. |
| `label` | `string \| null` | Translated label for the predicted status. |
| `value` | `string \| null` | Predicted volume percentage for volume actions, otherwise `null`. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present while the indicator is open. |
| `data-status` | `'pause' \| 'play' \| 'volume-off' \| 'volume-low' \| 'volume-high' \| 'captions-on' \| 'captions-off' \| 'fullscreen' \| 'exit-fullscreen' \| 'pip' \| 'exit-pip' \| string & {} \| null` | Predicted visual status for the handled input action. |
| `data-starting-style` | — | Present during the open transition. |
| `data-ending-style` | — | Present during the close transition. |

### Value

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: StatusIndicatorState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: StatusIndicatorState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: StatusIndicatorState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/volume-indicator -->

# VolumeIndicator

Display temporary visual feedback for keyboard and gesture volume actions

## Import

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

## Anatomy

```tsx
<VolumeIndicator.Root>
  <VolumeIndicator.Fill>
    <VolumeIndicator.Value />
  </VolumeIndicator.Fill>
</VolumeIndicator.Root>
```

## Behavior

`VolumeIndicator` displays feedback for `toggleMuted` and `volumeStep` actions emitted by a [`Hotkey`](https://videojs.org/docs/framework/react/reference/components/hotkey) or [`Gesture`](https://videojs.org/docs/framework/react/reference/components/gesture) in the same player `Container`. It does not react to mute buttons, volume sliders, direct player-store changes, or volume changes on their own.

The input event arrives before its action is resolved. The indicator uses the media snapshot from that moment to predict the next mute state and volume. `toggleMuted` predicts the opposite mute state. `volumeStep` adds its `value` to the snapshot volume and clamps the result from 0 to 1. A step whose clamped result is above 0 also predicts that mute will clear.

The root exposes the predicted level:

| `data-level` | Predicted state |
| --- | --- |
| `"off"` | Muted or volume is 0 |
| `"low"` | Unmuted volume is greater than 0 and at most 0.5 |
| `"high"` | Unmuted volume is greater than 0.5 |

`Value` displays the rounded percentage from 0% through 100%. `Fill` receives the same percentage through `--media-volume-fill`. Nest `Value` inside `Fill` so the progress treatment and text form one visual unit.

The indicator closes after `closeDelay`, which defaults to 800 milliseconds. Repeated handled actions update the current value and restart that close timer without replaying the entry transition. Each update uses the latest media snapshot; the component does not independently accumulate volume steps.

`VolumeIndicator.Root` stops rendering after its close transition.

When a nonzero `volumeStep` cannot move past an already-clamped edge, `data-min` or `data-max` is present for 300 milliseconds. Hitting the same edge again briefly clears the attribute, then restores it on the next task so a CSS boundary animation can restart. Merely reaching 0% or 100% does not trigger the boundary attribute until another step tries to move farther.

## Styling

| Attribute | Values | Description |
| --- | --- | --- |
| `data-open` | Present / absent | Present while the indicator is open |
| `data-level` | `"off"`, `"low"`, or `"high"` | Predicted volume level |
| `data-min` | Present / absent | Present briefly after a blocked downward step at minimum volume |
| `data-max` | Present / absent | Present briefly after a blocked upward step at maximum volume |
| `data-starting-style` | Present / absent | Present during the open transition |
| `data-ending-style` | Present / absent | Present during the close transition |

`--media-volume-fill` is set on the Fill part, not the Root. Read it from a Fill selector when sizing a progress treatment.

React renders standard DOM elements. Add separate `className` values to the Root and Fill:

```css
.volume-indicator__fill::before {
  width: var(--media-volume-fill, 0%);
}

.volume-indicator[data-starting-style],
.volume-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`VolumeIndicator` is visual feedback and does not create a live region. Keep volume and mute available through keyboard-operable controls, and pair the player with [`StatusAnnouncer`](https://videojs.org/docs/framework/react/reference/components/status-announcer) when state changes should be announced to screen readers. Do not make `VolumeIndicator.Value` a live region.

## Examples

### Basic Usage

Focus the player, then press M to mute or unmute. Use Arrow Up and Arrow Down to adjust volume by 5%.

**App.tsx**

```tsx
import { Container, createPlayer, Hotkey, VolumeIndicator } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-volume-indicator-basic" tabIndex={0}>
        <Video
          ref={(video) => {
            if (video) video.volume = 0.5;
          }}
          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
          autoPlay
          muted
          playsInline
          loop
        />
        <p className="react-volume-indicator-basic__instructions">Focus the player · M: mute · ↑/↓: volume ±5%</p>
        <VolumeIndicator.Root className="react-volume-indicator-basic__indicator" aria-hidden="true">
          <VolumeIndicator.Fill className="react-volume-indicator-basic__fill">
            <VolumeIndicator.Value className="react-volume-indicator-basic__value" />
          </VolumeIndicator.Fill>
        </VolumeIndicator.Root>
        <Hotkey keys="m" action="toggleMuted" />
        <Hotkey keys="ArrowUp" action="volumeStep" value={0.05} />
        <Hotkey keys="ArrowDown" action="volumeStep" value={-0.05} />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-volume-indicator-basic {
  position: relative;
}

.react-volume-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.react-volume-indicator-basic video {
  display: block;
  width: 100%;
}

.react-volume-indicator-basic__instructions {
  position: absolute;
  top: 10px;
  left: 50%;
  padding: 6px 10px;
  margin: 0;
  color: white;
  text-align: center;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
  translate: -50%;
}

.react-volume-indicator-basic__indicator {
  position: absolute;
  top: 50%;
  left: 50%;
  display: grid;
  min-width: 220px;
  padding: 18px 20px 34px;
  color: white;
  pointer-events: none;
  background: rgb(0 0 0 / 72%);
  border-radius: 12px;
  place-items: center;
  translate: -50% -50%;
  transition:
    opacity 160ms ease-in-out,
    scale 160ms ease-in-out;
}

.react-volume-indicator-basic__indicator::before {
  margin-bottom: 12px;
  font-size: 28px;
  line-height: 1;
}

.react-volume-indicator-basic__indicator[data-level="off"]::before {
  content: "🔇";
}

.react-volume-indicator-basic__indicator[data-level="low"]::before {
  content: "🔉";
}

.react-volume-indicator-basic__indicator[data-level="high"]::before {
  content: "🔊";
}

.react-volume-indicator-basic__fill {
  position: relative;
  width: 180px;
  height: 10px;
  background: rgb(255 255 255 / 25%);
  border-radius: 9999px;
}

.react-volume-indicator-basic__fill::before {
  position: absolute;
  inset-block: 0;
  left: 0;
  width: var(--media-volume-fill, 0%);
  content: "";
  background: currentColor;
  border-radius: inherit;
  transition: width 160ms linear;
}

.react-volume-indicator-basic__value {
  position: absolute;
  top: calc(100% + 6px);
  left: 50%;
  font-variant-numeric: tabular-nums;
  translate: -50%;
}

.react-volume-indicator-basic__indicator[data-starting-style],
.react-volume-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

@media (prefers-reduced-motion: no-preference) {
  .react-volume-indicator-basic__indicator[data-min],
  .react-volume-indicator-basic__indicator[data-max] {
    animation: react-volume-indicator-basic-shake 300ms linear;
  }
}

@keyframes react-volume-indicator-basic-shake {
  20% {
    translate: calc(-50% - 8px) -50%;
  }

  40% {
    translate: calc(-50% + 6px) -50%;
  }

  60% {
    translate: calc(-50% - 4px) -50%;
  }

  80% {
    translate: calc(-50% + 2px) -50%;
  }
}
```

## API Reference

### Root

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | — | Delay in milliseconds before the indicator closes. |
| `labels` | `Partial<InputIndicatorLabels>` | — | Internal translated label overrides supplied by framework adapters. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the indicator is open. |
| `generation` | `number` | Increments each time a volume input action updates the indicator. |
| `level` | `'off' \| 'low' \| 'high' \| null` | Predicted volume level after the input action. |
| `value` | `string \| null` | Predicted volume formatted as a percentage. |
| `fill` | `string \| null` | Predicted volume percentage used by the Fill part. |
| `min` | `boolean` | Whether a downward step tried to move past minimum volume. |
| `max` | `boolean` | Whether an upward step tried to move past maximum volume. |

#### Data attributes

| Attribute | Type | Description |
| --- | --- | --- |
| `data-open` | — | Present while the indicator is open. |
| `data-level` | `'off' \| 'low' \| 'high' \| null` | Predicted volume level as `"off"`, `"low"`, or `"high"`. |
| `data-min` | — | Present briefly when a downward step cannot lower the volume further. |
| `data-max` | — | Present briefly when an upward step cannot raise the volume further. |
| `data-starting-style` | — | Present during the open transition. |
| `data-ending-style` | — | Present during the close transition. |

#### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-volume-fill` | Current predicted volume percentage, set on the Fill part. |

### Fill

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: VolumeIndicatorState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: VolumeIndicatorState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: VolumeIndicatorState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Value

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: VolumeIndicatorState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: VolumeIndicatorState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: VolumeIndicatorState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/dialog -->

# Dialog

A modal dialog for application content, including players opened from a thumbnail

## Import

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

## Anatomy

```tsx
<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Backdrop />
  <Dialog.Popup>
    <Dialog.Title />
    <Dialog.Description />
    <Dialog.Close />
  </Dialog.Popup>
</Dialog.Root>
```

## Behavior

`Dialog` provides the modal interaction and accessibility behavior while your application supplies the content and styling. It is the general-purpose replacement for a `ModalDialog` use case such as opening a player from a thumbnail.

Use `Dialog.Trigger` to open the dialog. Use `open` with `onOpenChange` for controlled state, or `defaultOpen` for uncontrolled state. `Root` provides state without rendering an element, while `Popup` renders only while the dialog is open or closing.

The close part and Escape close the dialog. Other buttons inside the dialog, including player controls, do not close it.

Your application decides what opening and closing mean for the media. The example starts playback after opening and pauses it as soon as the dialog closes. Handle the promise returned by `play()`, since browsers can reject autoplay when it is not allowed.

Use [`AlertDialog`](https://videojs.org/docs/framework/react/reference/components/alert-dialog) for urgent messages that require acknowledgement. [`ErrorDialog`](https://videojs.org/docs/framework/react/reference/components/error-dialog) is the player-error specialization. Both use the same dialog behavior.

## Styling

Use the open and transition data attributes to style the modal and its animations:

| Attribute | Description |
| --- | --- |
| `data-open` | Present while the dialog is open, including its closing transition |
| `data-starting-style` | Present at the start of the opening transition |
| `data-ending-style` | Present during the closing transition |

React renders the backdrop and popup as separate DOM elements. Add a `className` to each part and style their transitions independently:

```css
.dialog-backdrop[data-starting-style],
.dialog-backdrop[data-ending-style],
.dialog-popup[data-starting-style],
.dialog-popup[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

The popup uses `role="dialog"` and `aria-modal="true"`. Include `Dialog.Title` so the dialog always has an accessible name. `Dialog.Description` is optional. These parts receive generated IDs connected through `aria-labelledby` and `aria-describedby`. The trigger receives `aria-haspopup`, `aria-controls`, and `aria-expanded`.

When the dialog opens, focus moves to an element with `autofocus`, the first focusable element, or the popup itself. Tab and Shift + Tab keep focus within the dialog, and content outside the dialog becomes inert. Closing restores focus to the trigger, or to the element that was focused before the dialog opened.

Dialogs inside the same player container share modal coordination. Opening one closes the current dialog and dismisses any open menu, tooltip, or popover before focus moves into the new popup.

## Examples

### Player modal

Open the video from its thumbnail. Playback starts when the dialog opens and pauses when it closes.

**App.tsx**

```tsx
import { Container, createPlayer, Dialog } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import { useEffect, useRef, useState } from 'react';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  const [open, setOpen] = useState(false);
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    if (open) void video.play().catch(() => {});
    else video.pause();
  }, [open]);

  return (
    <div className="react-dialog-basic">
      <Dialog.Root open={open} onOpenChange={setOpen}>
        <Dialog.Trigger className="react-dialog-basic__trigger">
          <img src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg" alt="" />
          <span>Play the video</span>
        </Dialog.Trigger>
        <Dialog.Backdrop className="react-dialog-basic__backdrop" />
        <Dialog.Popup className="react-dialog-basic__dialog">
          <div className="react-dialog-basic__popup">
            <Dialog.Title className="react-dialog-basic__title">Video title</Dialog.Title>
            <Dialog.Description className="react-dialog-basic__description">
              A video opened from a thumbnail.
            </Dialog.Description>
            <Dialog.Close className="react-dialog-basic__close">Close</Dialog.Close>
            <Player>
              <Container>
                <Video ref={videoRef} src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" controls muted playsInline />
              </Container>
            </Player>
          </div>
        </Dialog.Popup>
      </Dialog.Root>
    </div>
  );
}
```

**App.css**

```css
.react-dialog-basic {
  position: relative;
  min-height: 320px;
}

.react-dialog-basic__trigger {
  display: grid;
  gap: 10px;
  width: min(100%, 420px);
  padding: 0 0 12px;
  overflow: hidden;
  color: white;
  cursor: pointer;
  background: #111827;
  border: 0;
  border-radius: 12px;
}

.react-dialog-basic__trigger img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.react-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  z-index: 1;
  background: rgb(3 7 18 / 80%);
  transition: opacity 200ms ease;
}

.react-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 2;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 20px;
  transition: opacity 150ms ease;
}

.react-dialog-basic__backdrop[data-starting-style],
.react-dialog-basic__backdrop[data-ending-style],
.react-dialog-basic__dialog[data-starting-style],
.react-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.react-dialog-basic__popup {
  position: relative;
  width: 100%;
  max-width: 560px;
  padding: 16px;
  color: white;
  background: #111827;
  border-radius: 12px;
}

.react-dialog-basic__title {
  margin: 0 0 4px;
  font-size: 1.125rem;
  font-weight: 600;
}

.react-dialog-basic__description {
  margin: 0 0 12px;
}

.react-dialog-basic__close {
  position: absolute;
  top: 12px;
  right: 12px;
  padding: 6px 12px;
  color: #111827;
  cursor: pointer;
  background: white;
  border: 0;
  border-radius: 9999px;
}

.react-dialog-basic video {
  display: block;
  width: 100%;
}

@media (prefers-reduced-motion: reduce) {
  .react-dialog-basic__backdrop,
  .react-dialog-basic__dialog {
    transition: none;
  }
}
```

## API Reference

### Root

Manages dialog state and provides it to the compound parts.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnEscape` | `boolean` | `true` | Whether pressing Escape closes the dialog. |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
| `open` | `boolean` | `false` | Controlled open state. When set, the consumer is responsible for toggling. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the dialog is currently open. |
| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
| `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
| `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Backdrop

Presentational layer behind a dialog while it is rendered, including its exit transition.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Close

Renders a button that closes the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Description

Renders the description announced with the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Popup

Renders the modal dialog while it is open.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Title

Renders the heading that labels the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Trigger

Renders a button that opens the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/alert-dialog -->

# AlertDialog

A modal alert dialog for urgent messages that require acknowledgement

## Import

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

## Anatomy

```tsx
<AlertDialog.Root>
  <AlertDialog.Backdrop />
  <AlertDialog.Popup>
    <AlertDialog.Title />
    <AlertDialog.Description />
    <AlertDialog.Close />
  </AlertDialog.Popup>
</AlertDialog.Root>
```

## Behavior

Use an alert dialog for an urgent message that interrupts the user and requires acknowledgement. Your application controls when it opens and supplies its content.

`AlertDialog.Root` adds alert semantics, while the other `AlertDialog` parts are re-exported from [`Dialog`](https://videojs.org/docs/framework/react/reference/components/dialog). For general modal content, including a player opened from a thumbnail, use `Dialog.Root` instead.

Use `open` with `onOpenChange` for controlled state, or `defaultOpen` for uncontrolled state. `Root` provides state without rendering an element, while `Popup` renders only while the dialog is open.

The close part and Escape close the dialog. The dialog stays rendered during a closing transition, then restores focus to the element that was focused before it opened.

## Styling

Use the open and transition data attributes to style visibility and animations:

| Attribute | Description |
| --- | --- |
| `data-open` | Present while the dialog is open, including its closing transition |
| `data-starting-style` | Present at the start of the opening transition |
| `data-ending-style` | Present during the closing transition |

React renders separate backdrop and popup elements. Add a `className` to each part and style them independently:

```css
.alert-dialog-backdrop[data-starting-style],
.alert-dialog-backdrop[data-ending-style],
.alert-dialog-popup[data-starting-style],
.alert-dialog-popup[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

The dialog uses `role="alertdialog"` and `aria-modal="true"`. The title and description receive generated IDs that are connected with `aria-labelledby` and `aria-describedby`. Focus moves into the dialog when it opens, stays within it while open, and returns to the previously focused element when it closes. Content outside the dialog is inert while it is open. Pressing Escape closes the dialog.

## Examples

### Basic usage

**App.tsx**

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

export default function BasicUsage() {
  const [open, setOpen] = useState(false);

  return (
    <div className="react-alert-dialog-basic">
      <button className="react-alert-dialog-basic__trigger" type="button" onClick={() => setOpen(true)}>
        Open alert dialog
      </button>
      <AlertDialog.Root open={open} onOpenChange={setOpen}>
        <AlertDialog.Backdrop className="react-alert-dialog-basic__backdrop" />
        <AlertDialog.Popup className="react-alert-dialog-basic__dialog">
          <AlertDialog.Title className="react-alert-dialog-basic__title">Stop playback?</AlertDialog.Title>
          <AlertDialog.Description className="react-alert-dialog-basic__description">
            Your current playback position will be lost.
          </AlertDialog.Description>
          <AlertDialog.Close className="react-alert-dialog-basic__close">Continue</AlertDialog.Close>
        </AlertDialog.Popup>
      </AlertDialog.Root>
    </div>
  );
}
```

**App.css**

```css
.react-alert-dialog-basic {
  position: relative;
  display: grid;
  place-items: center;
  min-height: 240px;
  overflow: hidden;
  background: #111827;
  border-radius: 12px;
}

.react-alert-dialog-basic__trigger,
.react-alert-dialog-basic__close {
  padding: 8px 16px;
  color: #111827;
  cursor: pointer;
  background: #fff;
  border: 0;
  border-radius: 9999px;
}

.react-alert-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  background: rgb(3 7 18 / 92%);
  transition: opacity 150ms ease;
}

.react-alert-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 1;
  display: grid;
  gap: 12px;
  place-content: center;
  padding: 32px;
  color: #fff;
  text-align: center;
  transition: opacity 150ms ease;
}

.react-alert-dialog-basic__backdrop[data-starting-style],
.react-alert-dialog-basic__backdrop[data-ending-style],
.react-alert-dialog-basic__dialog[data-starting-style],
.react-alert-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.react-alert-dialog-basic__title {
  font-size: 20px;
  font-weight: 600;
}

.react-alert-dialog-basic__description {
  color: #d1d5db;
}

.react-alert-dialog-basic__close {
  justify-self: center;
}
```

## API Reference

### Root

Manages alert dialog state and provides it to the shared dialog parts.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnEscape` | `boolean` | — | Whether pressing Escape closes the dialog. |
| `defaultOpen` | `boolean` | — | Initial open state for uncontrolled usage. |
| `open` | `boolean` | — | Controlled open state. When set, the consumer is responsible for toggling. |

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the dialog is currently open. |
| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
| `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
| `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |

### Backdrop

Presentational layer behind a dialog while it is rendered, including its exit transition.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Close

Renders a button that closes the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Description

Renders the description announced with the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Popup

Renders the modal dialog while it is open.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Title

Renders the heading that labels the dialog.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/error-dialog -->

# ErrorDialog

An alert dialog that presents and dismisses playback errors

## Import

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

## Anatomy

```tsx
<ErrorDialog.Root>
  <ErrorDialog.Backdrop />
  <ErrorDialog.Popup>
    <ErrorDialog.Title />
    <ErrorDialog.Description />
    <ErrorDialog.Close />
  </ErrorDialog.Popup>
</ErrorDialog.Root>
```

## Behavior

`ErrorDialog` is a specialized root driven by the player’s [error feature](https://videojs.org/docs/framework/react/reference/api/feature-error). It uses alert semantics and reuses the backdrop, popup, title, description, and close parts from [`Dialog`](https://videojs.org/docs/framework/react/reference/components/dialog); it is not nested inside `AlertDialog`. It opens when the attached media reports an error and stays hidden otherwise. Closing it dismisses the current error in the player store.

The title, description, and close label use localized default text. Provide children to any of those parts to replace its default content. Known media error codes use the matching translated message, while custom error messages are shown as written.

The included player skins already render an error dialog. Compose this component directly when building a custom skin.

## Styling

Use `data-open`, `data-starting-style`, and `data-ending-style` to style visibility and transitions.

React renders the backdrop and popup as separate DOM elements. Add a `className` to each part and style their transitions independently:

```css
.error-dialog-backdrop[data-starting-style],
.error-dialog-backdrop[data-ending-style],
.error-dialog-popup[data-starting-style],
.error-dialog-popup[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

The popup uses `role="alertdialog"`. Its title and description are connected with `aria-labelledby` and `aria-describedby`.

Modality is scoped to the player container rather than the page. While the error is open, the rest of the container is inert and focus that lands elsewhere inside it returns to the popup, but content outside the player stays interactive and `aria-modal` is omitted. Only when the popup renders outside the container does the dialog fall back to document-wide modality: `aria-modal="true"`, Tab cycling within the popup, and everything outside it inert.

Pressing Escape or activating the close part dismisses the error.

## Examples

The example replaces the video source with invalid local data so the media element reports an error without making a failing network request.

### Basic usage

**App.tsx**

```tsx
import { Container, createPlayer, ErrorDialog } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';
import { useRef } from 'react';

const { Player } = createPlayer({ features: videoFeatures });
const brokenSource = 'data:video/mp4;base64,AAAA';

export default function BasicUsage() {
  const videoRef = useRef<HTMLVideoElement>(null);

  const triggerError = () => {
    const video = videoRef.current;
    if (!video) return;

    video.src = brokenSource;
    video.load();
  };

  return (
    <Player>
      <Container className="react-error-dialog-basic">
        <Video
          ref={videoRef}
          className="react-error-dialog-basic__video"
          src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
          autoPlay
          muted
          playsInline
          loop
        />
        <button className="react-error-dialog-basic__trigger" type="button" onClick={triggerError}>
          Trigger a playback error
        </button>
        <ErrorDialog.Root>
          <ErrorDialog.Backdrop className="react-error-dialog-basic__backdrop" />
          <ErrorDialog.Popup className="react-error-dialog-basic__dialog">
            <ErrorDialog.Title className="react-error-dialog-basic__title" />
            <ErrorDialog.Description className="react-error-dialog-basic__description" />
            <ErrorDialog.Close className="react-error-dialog-basic__close" />
          </ErrorDialog.Popup>
        </ErrorDialog.Root>
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-error-dialog-basic {
  position: relative;
  display: block;
  overflow: hidden;
  border-radius: 12px;
}

.react-error-dialog-basic__video {
  display: block;
  width: 100%;
}

.react-error-dialog-basic__trigger,
.react-error-dialog-basic__close {
  padding: 8px 16px;
  color: #111827;
  cursor: pointer;
  background: #fff;
  border: 0;
  border-radius: 9999px;
}

.react-error-dialog-basic__trigger {
  position: absolute;
  bottom: 16px;
  left: 16px;
}

.react-error-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  background: rgb(3 7 18 / 92%);
  transition: opacity 150ms ease;
}

.react-error-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 1;
  display: grid;
  gap: 12px;
  place-content: center;
  padding: 32px;
  color: #fff;
  text-align: center;
  transition: opacity 150ms ease;
}

.react-error-dialog-basic__backdrop[data-starting-style],
.react-error-dialog-basic__backdrop[data-ending-style],
.react-error-dialog-basic__dialog[data-starting-style],
.react-error-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.react-error-dialog-basic__title {
  font-size: 20px;
  font-weight: 600;
}

.react-error-dialog-basic__description {
  color: #d1d5db;
}

.react-error-dialog-basic__close {
  justify-self: center;
}
```

## API Reference

### Root

Opens from player error state and provides it to the shared dialog parts.

#### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `transitionStarting` | `boolean` | Whether the open transition is in progress. |
| `transitionEnding` | `boolean` | Whether the close transition is in progress. |
| `open` | `boolean` | Whether the dialog is currently open. |
| `status` | `'idle' \| 'starting' \| 'ending'` | Current phase of the transition lifecycle. |
| `titleId` | `string \| undefined` | Element ID of the dialog title, used for `aria-labelledby`. |
| `descriptionId` | `string \| undefined` | Element ID of the dialog description, used for `aria-describedby`. |

### Close

Renders a localized button that closes the dialog and dismisses the player error.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Description

Renders the localized playback error message, or authored children when provided.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Title

Renders the localized error dialog heading, or authored children when provided.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

### Backdrop

Presentational layer behind a dialog while it is rendered, including its exit transition.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

### Popup

Renders the modal dialog while it is open.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string \| ((state: DialogState) => string \| undefined)` | — | Class name or function returning class name from state. |
| `render` | `ReactElement \| ((props: HTMLProps, state: DialogState) => ReactElement \| null)` | — | Render prop for custom element. |
| `style` | `CSSProperties \| ((state: DialogState) => CSSProperties \| undefined)` | — | Style or function returning style from state. |

#### Data attributes

| Attribute | Description |
| --- | --- |
| `data-open` | Present when the dialog is open. |
| `data-starting-style` | Present during the open transition. |
| `data-ending-style` | Present during the close transition. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/gesture -->

# Gesture

Map tap and double-tap gestures to player actions

## Import

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

## Anatomy

```tsx
<Gesture type="doubletap" region="right" pointer="touch" action="seekStep" value={10} />
```

## Behavior

`Gesture` is a behavior component: it renders no visible interface. Place it inside a [Container](https://videojs.org/docs/framework/react/reference/components/player-container) to map a `tap` or `doubletap` gesture to a player action.

A tap must use the primary pointer and complete within 250 milliseconds. When a matching double-tap gesture exists, the first tap waits briefly to see whether a second tap follows.

Use `pointer` to accept only `mouse`, `touch`, or `pen` input. Use `region` to divide the container horizontally:

- Left and right regions split the container into halves.
- Left, center, and right regions split it into thirds.
- A center-only region covers the full container.
- A single left or right region covers that half of the container.

An unregional gesture acts as a fallback outside the active regions. When several registrations match the same gesture, the first registration wins.

Choose a built-in `action` from the API reference below, or use an application-defined name to call a same-named action on the player store. Pass `value` as seconds for `seekStep` or as a volume delta such as `0.05` or `-0.05` for `volumeStep`. When omitted, these actions use the 10-second or five-percentage-point default. A left-region seek gesture uses the negative step. Unknown action names do nothing and warn in development.

## Accessibility

Gestures supplement visible, keyboard-operable controls; they should never be the only way to perform an action. Gestures ignore pointer activity that begins on interactive controls, links, form fields, menu items, or elements marked with `data-interactive`.

## Examples

### Basic Usage

This example follows the common video-player pattern: click to play or pause, double-click the left or right side to seek ten seconds, and double-click the center to toggle fullscreen.

**App.tsx**

```tsx
import { Container, createPlayer, Gesture, PlayButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-gesture-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <p className="react-gesture-basic__instructions">Click: play/pause · Double-click: −10s · fullscreen · +10s</p>
        <PlayButton
          className="react-gesture-basic__button"
          render={(props, state) => (
            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
          )}
        />
        <Gesture type="tap" action="togglePaused" pointer="mouse" region="center" />
        <Gesture type="doubletap" action="seekStep" value={-10} region="left" />
        <Gesture type="doubletap" action="toggleFullscreen" region="center" />
        <Gesture type="doubletap" action="seekStep" value={10} region="right" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-gesture-basic {
  position: relative;
}

.react-gesture-basic video {
  width: 100%;
}

.react-gesture-basic__instructions {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  pointer-events: none;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.react-gesture-basic__button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding: 8px 20px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 80%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `action` (required) | `'togglePaused' \| 'toggleMuted' \| 'toggleFullscreen' \| 'toggleSubtitles' \| 'togglePictureInPicture' \| 'toggleControls' \| 'seekStep' \| 'volumeStep' \| 'speedUp' \| 'speedDown' \| string & {}` | — | Built-in player action or same-named custom store action to run when the gesture is recognized. |
| `type` (required) | `'tap' \| 'doubletap'` | — | Gesture to recognize. |
| `disabled` | `boolean` | — | Whether the gesture is disabled. |
| `pointer` | `'mouse' \| 'touch' \| 'pen'` | — | Pointer type that may activate the gesture. All pointer types are accepted when omitted. |
| `region` | `'left' \| 'center' \| 'right'` | — | Optional horizontal part of the container that may activate the gesture. |
| `value` | `number` | — | Numeric value passed to actions such as `seekStep` and `volumeStep`. Uses their shared step when omitted. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/hotkey -->

# Hotkey

Register a keyboard shortcut that invokes a player action

## Import

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

## Anatomy

```tsx
<Hotkey keys="Space" action="togglePaused" />
```

## Behavior

`Hotkey` is a behavior component: it renders no visible interface. Place it inside a [Container](https://videojs.org/docs/framework/react/reference/components/player-container) to register one key pattern and player action.

By default, the shortcut responds while the player container has focus. Set `target="document"` only when the shortcut should apply across the entire document.

Key patterns are case-insensitive and may use:

- Named keys such as `Space`, `ArrowLeft`, and `ArrowRight`.
- Exact modifiers such as `Ctrl+k`, `Shift+f`, `Alt+m`, and `Meta+k`.
- `Mod` for `Meta` on macOS and `Ctrl` elsewhere.
- The special `0-9` range for digit-based seeking.

Choose an `action` from the API reference below. Pass `value` as seconds for `seekStep`, a volume delta such as `0.05` or `-0.05` for `volumeStep`, or a percentage from 0 to 100 for `seekToPercent`. When omitted, `seekStep` defaults to 10 seconds and `volumeStep` defaults to five percentage points; `ArrowLeft`, `j`, and `ArrowDown` use the negative step. When `value` is omitted from `seekToPercent` with `keys="0-9"`, the pressed digit supplies the percentage.

Toggle actions ignore held-key repeats. Step, rate, and percentage actions may repeat. A matched shortcut prevents the browser’s default behavior. Unmodified shortcuts are ignored in editable fields, and Space or Enter still activates focused buttons, links, and sliders normally.

## Accessibility

Hotkeys supplement operable controls; they should never be the only way to perform an action. Built-in buttons use matching hotkey registrations to expose `aria-keyshortcuts`, and their tooltips can display the registered shortcut.

## Examples

### Basic Usage

This player uses Space to play or pause, M to mute, and the arrow keys to seek by five seconds. Click the player first to focus its container.

**App.tsx**

```tsx
import { Container, createPlayer, Hotkey, PlayButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-hotkey-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <p className="react-hotkey-basic__instructions">Space: play/pause · M: mute · ←/→: seek</p>
        <PlayButton
          className="react-hotkey-basic__button"
          render={(props, state) => (
            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
          )}
        />
        <Hotkey keys="Space" action="togglePaused" />
        <Hotkey keys="m" action="toggleMuted" />
        <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
        <Hotkey keys="ArrowRight" action="seekStep" value={5} />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-hotkey-basic {
  position: relative;
}

.react-hotkey-basic video {
  width: 100%;
}

.react-hotkey-basic__instructions {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.react-hotkey-basic__button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding: 8px 20px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 80%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `action` (required) | `'togglePaused' \| 'toggleMuted' \| 'toggleFullscreen' \| 'toggleSubtitles' \| 'togglePictureInPicture' \| 'seekStep' \| 'volumeStep' \| 'speedUp' \| 'speedDown' \| 'seekToPercent'` | — | Player action to run when the key pattern matches. |
| `keys` (required) | `string` | — | Key pattern to match, such as `Space`, `ArrowRight`, or `Mod+k`. |
| `disabled` | `boolean` | — | Whether the hotkey is disabled. |
| `target` | `'player' \| 'document'` | — | Whether to listen on the player container or the document. |
| `value` | `number` | — | Numeric value passed to actions such as `seekStep`, `volumeStep`, and `seekToPercent`. Arrow-key seek and volume actions use their shared input-action step when omitted. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/status-announcer -->

# StatusAnnouncer

Announce player state changes through a persistent status live region

## Import

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

## Anatomy

```tsx
<StatusAnnouncer />
```

## Behavior

`StatusAnnouncer` watches player-store snapshots, so it reports changes made by buttons, sliders, custom controls, or direct player actions. It does not depend on [`Hotkey`](https://videojs.org/docs/framework/react/reference/components/hotkey) or [`Gesture`](https://videojs.org/docs/framework/react/reference/components/gesture) events.

The first snapshot establishes a baseline without announcing it. Later changes are handled in two groups:

| Timing | Changes |
| --- | --- |
| Immediate | Playing or paused, captions on or off, fullscreen entered or exited, picture-in-picture entered or exited, and playback rate |
| Debounced by 200 milliseconds | The final volume or mute value and the final time after a completed seek |

Regular playback-time updates are ignored. A seek announcement is queued only after `seeking` changes from `true` to `false` at a different time. When several immediate states change in one snapshot, their translated labels are combined into one announcement.

The component always renders with `role="status"`. Its `[data-status-announcer-content]` child is replaced for every announcement, including repeated text, so assistive technology receives a fresh live-region change. After `closeDelay`, which defaults to 800 milliseconds, the label is cleared while the status region remains rendered.

Announcements use the active Video.js locale and translations.

Use the `labels` prop to override individual translated labels for one announcer.

## Styling

`StatusAnnouncer` is not visually hidden by the primitive. Apply a visually-hidden class while keeping it in the accessibility tree. Do not use `display: none`, `visibility: hidden`, or the `hidden` attribute.

Add a `className` to the component:

```css
.status-announcer {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  white-space: nowrap;
  border: 0;
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
}
```

## Accessibility

The `status` role provides implicit polite live-region behavior, so the component does not add an explicit `aria-live` attribute.

Keep one announcer inside each player `Container` whose state changes should be reported.

Debounced volume and completed-seek announcements are suppressed while an element with `role="slider"` inside the same container has focus. The focused slider provides its own value feedback, and suppressing the separate status message avoids duplicate announcements. A focused slider outside that container does not suppress it.

Use [`SeekIndicator`](https://videojs.org/docs/framework/react/reference/components/seek-indicator) for temporary visual seek feedback. Keep that visual value out of a live region; `StatusAnnouncer` owns the accessible announcement.

## Examples

### Basic Usage

Use the playback button for an immediate announcement and the mute button for a debounced announcement. The sliders provide their own focused value feedback, so `StatusAnnouncer` suppresses its duplicate volume and completed-seek message.

**App.tsx**

```tsx
import {
  Container,
  createPlayer,
  MuteButton,
  PlayButton,
  StatusAnnouncer,
  TimeSlider,
  VolumeSlider,
} from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

import './BasicUsage.css';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-status-announcer-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <p className="react-status-announcer-basic__instructions">
          These controls announce status changes to screen readers.
        </p>
        <div className="react-status-announcer-basic__controls">
          <PlayButton
            className="react-status-announcer-basic__button"
            render={(props, state) => (
              <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
            )}
          />
          <MuteButton
            className="react-status-announcer-basic__button"
            render={(props, state) => <button {...props}>{state.muted ? 'Unmute' : 'Mute'}</button>}
          />
          <VolumeSlider.Root className="react-status-announcer-basic__volume-slider">
            <VolumeSlider.Track className="react-status-announcer-basic__track">
              <VolumeSlider.Fill className="react-status-announcer-basic__fill" />
            </VolumeSlider.Track>
            <VolumeSlider.Thumb className="react-status-announcer-basic__thumb" />
          </VolumeSlider.Root>
        </div>
        <TimeSlider.Root className="react-status-announcer-basic__time-slider">
          <TimeSlider.Track className="react-status-announcer-basic__track">
            <TimeSlider.Buffer className="react-status-announcer-basic__buffer" />
            <TimeSlider.Fill className="react-status-announcer-basic__fill" />
          </TimeSlider.Track>
          <TimeSlider.Thumb className="react-status-announcer-basic__thumb" />
        </TimeSlider.Root>
        <StatusAnnouncer className="react-status-announcer-basic__announcer" />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-status-announcer-basic {
  position: relative;
}

.react-status-announcer-basic video {
  display: block;
  width: 100%;
}

.react-status-announcer-basic__instructions {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.react-status-announcer-basic__controls {
  position: absolute;
  right: 12px;
  bottom: 36px;
  left: 12px;
  display: flex;
  gap: 8px;
  align-items: center;
}

.react-status-announcer-basic__button {
  padding: 7px 14px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 85%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.react-status-announcer-basic__volume-slider,
.react-status-announcer-basic__time-slider {
  position: relative;
  display: flex;
  align-items: center;
  height: 20px;
  cursor: pointer;
}

.react-status-announcer-basic__volume-slider {
  width: 100px;
}

.react-status-announcer-basic__time-slider {
  position: absolute;
  right: 12px;
  bottom: 8px;
  left: 12px;
}

.react-status-announcer-basic__track {
  position: absolute;
  right: 0;
  left: 0;
  height: 5px;
  overflow: hidden;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.react-status-announcer-basic__buffer,
.react-status-announcer-basic__fill {
  position: absolute;
  top: 0;
  left: 0;
  height: 100%;
  border-radius: inherit;
}

.react-status-announcer-basic__buffer {
  width: var(--media-slider-buffer);
  background: rgb(255 255 255 / 30%);
}

.react-status-announcer-basic__fill {
  width: var(--media-slider-fill);
  background: white;
}

.react-status-announcer-basic__thumb {
  position: absolute;
  left: var(--media-slider-fill);
  width: 14px;
  height: 14px;
  background: white;
  border-radius: 50%;
  box-shadow: 0 1px 3px rgb(0 0 0 / 40%);
  translate: -50%;
}

.react-status-announcer-basic__announcer {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  white-space: nowrap;
  border: 0;
  clip: rect(0 0 0 0);
  clip-path: inset(50%);
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | — | Delay in milliseconds before the current announcement label is cleared. |
| `labels` | `Partial<StatusAnnouncerLabels>` | — | Overrides for the translated announcement labels. |
| `shouldAnnounce` | `(() => boolean)` | — | Whether debounced seek and volume changes should be announced. |

### State

State is accessible via the `render`, `className`, and `style` props.

| Property | Type | Description |
| --- | --- | --- |
| `generation` | `number` | Increments for each announcement so repeated labels replace the live-region content. |
| `label` | `string \| null` | Current announcement text, or `null` when the live region is empty. |

---

<!-- Source: https://videojs.org/docs/framework/react/reference/components/icons -->

# Icons

The SVG icon sets used by the packaged skins, as React components, SVG strings, and the media-icon element

The icons the packaged skins render. Skin source added with the [Shadcn registry](https://videojs.org/docs/guides/installation/shadcn?framework=react) imports its icons from these modules, and your own controls can use them too.

Each icon is a React component that renders an inline `<svg>`.

## Import

```tsx
import { PlayIcon } from "@videojs/react/icons";
```

## Icon sets

Three sets ship with the same icon names and different designs.

| Set | Module | Used by |
| --- | --- | --- |
| Default | `@videojs/react/icons` | The default skins, such as [`VideoSkin`](https://videojs.org/docs/framework/react/reference/components/video-skin) |
| Neutral | `@videojs/react/icons/neutral` | The neutral skins, such as [`NeutralVideoSkin`](https://videojs.org/docs/framework/react/reference/components/video-neutral-skin) |
| Compat | `@videojs/react/icons/compat` | The compat skins, such as [`CompatVideoSkin`](https://videojs.org/docs/framework/react/reference/components/video-compat-skin) |

## Available icons

| Export |
| --- |
| `AirPlayEnterIcon` |
| `AirPlayExitIcon` |
| `CaptionsOffIcon` |
| `CaptionsOnIcon` |
| `CastEnterIcon` |
| `CastExitIcon` |
| `CheckIcon` |
| `ChevronIcon` |
| `FullscreenEnterIcon` |
| `FullscreenExitIcon` |
| `GearIcon` |
| `PauseIcon` |
| `PipEnterIcon` |
| `PipExitIcon` |
| `PlayIcon` |
| `QualityIcon` |
| `RestartIcon` |
| `SeekIcon` |
| `SpeechIcon` |
| `SpeedIcon` |
| `SpinnerIcon` |
| `SwitchesIcon` |
| `VolumeHighIcon` |
| `VolumeLowIcon` |
| `VolumeOffIcon` |

## Props

Icons accept `IconProps`, the standard SVG element props (`SVGProps<SVGSVGElement>`), and forward their ref to the `<svg>`. Props you pass override the defaults:

| Attribute | Default |
| --- | --- |
| `width`, `height` | `18` |
| `viewBox` | `0 0 18 18` |
| `fill` | `currentColor` |
| `aria-hidden` | `true` |

```tsx
import { PlayButton } from "@videojs/react";
import { PauseIcon, PlayIcon } from "@videojs/react/icons";

<PlayButton
  render={(props, state) => (
    <button {...props}>
      {state.paused ? <PlayIcon className="icon" /> : <PauseIcon className="icon" />}
    </button>
  )}
/>
```

## Styling

Icons use `fill="currentColor"`, so they take the text color of their parent. They are drawn on an 18×18 grid and render most sharply at 18px or a whole multiple, such as 36px.

```css
.icon {
  width: 36px;
  height: 36px;
  color: white;
}
```

## Accessibility

Every icon renders with `aria-hidden="true"`. Give the surrounding control its accessible name. Built-in buttons, such as the [play button](https://videojs.org/docs/framework/react/reference/components/play-button), provide one automatically.