# Video.js v10 — HTML Components (complete)

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

---

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

# video-player

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

The `<video-player>` element is the state boundary of your player. It creates a store and makes it available to every element inside it via context. Every player needs exactly one.

```html
<video-player>
  <!-- Everything inside can access the player store -->
  <media-container>
    <video src="video.mp4"></video>
  </media-container>
</video-player>
```

## How it’s created

For most users, importing from `@videojs/html/video/player` registers a ready-to-use `<video-player>` element with the standard video [features](https://videojs.org/docs/framework/html/guides/features) (bundled as a [preset](https://videojs.org/docs/framework/html/guides/presets)):

```ts
import '@videojs/html/video/player';
```

```html
<video-player>
  <media-container>
    <video src="video.mp4"></video>
  </media-container>
</video-player>
```

If you need a custom feature set or tag name, use `createPlayer()` to get the configured `PlayerElement`. Extend `ContainerElement` separately when you need custom container behavior:

**my-player.ts**

```ts
import { ContainerElement, createPlayer } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { PlayerElement: MyPlayer } = createPlayer({ features: videoFeatures });

class MyContainer extends ContainerElement {}
customElements.define('my-player', MyPlayer);
customElements.define('my-container', MyContainer);
```

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

## What lives inside it

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

```html
<video-player>
  <video-skin>               <!-- skin — includes container + controls -->
    <video src="..."></video> <!-- media component -->
  </video-skin>
  <my-custom-overlay></my-custom-overlay> <!-- your own element — can use PlayerController -->
</video-player>
```

## No visual presence

Packaged skins make `<video-player>` boxless with `display: contents`. Width, height, positioning, transforms, and `getBoundingClientRect()` do not describe a visible player box there. Put layout and measurements on the [`<media-container>`](https://videojs.org/docs/framework/html/reference/components/player-container) instead.

If you omit `<video-skin>` and import only the player and media components, those skin styles are not loaded. The player element still owns state, not layout, so add and style a `<media-container>` instead of using the player itself as the layout surface.

## Accessing state

Use the preset’s typed `PlayerController` to subscribe to store state from any custom element inside the player:

**play-pause-button.ts**

```ts
import { UIElement, selectPlayback } from '@videojs/html';
import { PlayerController } from '@videojs/html/video';

class PlayPauseButton extends UIElement {
  readonly #playback = new PlayerController(this, selectPlayback);

  connectedCallback() {
    super.connectedCallback();
    this.addEventListener('click', this.#togglePlayback);
  }

  disconnectedCallback() {
    this.removeEventListener('click', this.#togglePlayback);
    super.disconnectedCallback();
  }

  readonly #togglePlayback = () => {
    const playback = this.#playback.value;
    if (!playback) return;

    playback.paused ? playback.play() : playback.pause();
  };
}

customElements.define('play-pause-button', PlayPauseButton);
```

- [PlayerController reference](https://videojs.org/docs/framework/html/reference/api/player-controller)

## Extended player layouts

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

```html
<video-player>
  <media-container>
    <video src="video.mp4"></video>
    <media-controls><media-controls-content>...</media-controls-content></media-controls>  <!-- goes fullscreen with the video -->
  </media-container>

  <media-transcript></media-transcript>     <!-- outside container — still has store access -->
  <playlist-sidebar></playlist-sidebar>     <!-- outside container — still has store access -->
</video-player>
```

## Lifecycle

Video.js elements clean up after themselves when you remove them from the page:

- `<video-player>` and the UI elements destroy themselves two animation frames after they’re removed. Destroying the player also destroys its store.
- Media components such as `<hlsjs-video>` tear down their playback engine in a microtask after they’re removed.

Moving an element synchronously, removing it and inserting it elsewhere with no `await` in between, triggers neither. To keep an element through a longer move, add the `keep-alive` attribute:

```html
<video-player keep-alive>
  <media-container keep-alive>
    <hlsjs-video src="/stream.m3u8" keep-alive></hlsjs-video>
  </media-container>
</video-player>
```

`keep-alive` applies only to the element that carries it; descendants don’t inherit it. Set it on every Video.js element in the tree you move. Packaged skins don’t pass it to the controls inside them, so move a player that uses a packaged skin synchronously. An element with `keep-alive` is never destroyed automatically. When you’re finished with it, call `destroy()` on the player and UI elements, and `adapter.destroy()` on media components, which release their engine that way. A destroyed element can’t be reconnected; create a new one instead.

---

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

# media-container

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

The `<media-container>` is the player’s physical surface. It defines the visual boundary, registers the fullscreen and activity target, and gives gesture and hotkey elements a shared interaction surface. It lives inside a [`<video-player>`](https://videojs.org/docs/framework/html/reference/components/player).

```html
<video-player>
  <media-container>
    <video src="video.mp4"></video>
    <media-controls><media-controls-content>...</media-controls-content></media-controls>
  </media-container>
</video-player>
```

## How it’s created

Import the standard player entry point and the container. `video/player` registers only `<video-player>`; `ui/container` registers `<media-container>`:

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
```

```html
<video-player>
  <media-container>
    <video src="video.mp4"></video>
  </media-container>
</video-player>
```

For custom behavior, extend the same `ContainerElement` used by the built-in player:

**my-player.ts**

```ts
import { ContainerElement } from '@videojs/html';

class MyContainer extends ContainerElement {}
customElements.define('my-container', MyContainer);
```

Extending `ContainerElement` automatically registers the element with the nearest player when it connects and releases that registration when it disconnects.

Import `@videojs/html/ui/container` when you only need to register the standard `<media-container>` element.

## 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 `<media-container>`, not `<video-player>`. Place overlays inside it, use it as their positioning context, and measure it when your app needs the rendered player size.

```css
.player-surface {
  position: relative;
  display: block;
  width: 640px;
  aspect-ratio: 16 / 9;
}
```

```html
<media-container class="player-surface">
  <video src="video.mp4"></video>
  <media-controls><media-controls-content>...</media-controls-content></media-controls>
</media-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.

Custom video elements such as `<mux-video>` and `<hlsjs-video>` do not create their own layout boxes: their inner `<video>` fills the parent. Size and measure `<media-container>`, not `<mux-video>` or `<hlsjs-video>`. Native `<video>` and `<audio>` elements still render their own boxes.

### Media attachment

Media discovery is handled by the player provider, not the container. Media components like `<hlsjs-video>` register themselves via context when they connect. Plain `<video>` and `<audio>` elements are tracked automatically, including when they are added, removed, or replaced after connection. No `slot="media"` attribute is needed.

### 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 [`<media-gesture>`](https://videojs.org/docs/framework/html/reference/components/gesture) element.
- **Keyboard controls** — Spacebar to play/pause, arrow keys to seek, and other keyboard shortcuts scoped to the container. Configured via the `<media-hotkey>` element.

### Popup coordination

Each container owns one popup group. Opening a root [menu](https://videojs.org/docs/framework/html/reference/components/menu) or [popover](https://videojs.org/docs/framework/html/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/html/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 `<video-skin>` for the player’s outer size and aspect ratio. Importing the skin registers the styles that make the built-in container fill that space and position the media, controls, poster, and overlays.

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

## Inside vs. outside the container

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

```html
<video-player>
  <media-container>
    <video src="video.mp4"></video>
    <media-controls><media-controls-content>...</media-controls-content></media-controls>  <!-- fullscreen, activity detection, gestures -->
  </media-container>

  <media-transcript></media-transcript>     <!-- state & actions, but no container behaviors -->
  <playlist-sidebar></playlist-sidebar>     <!-- state & actions, but no container behaviors -->
</video-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/html/reference/components/controls -->

# media-controls

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

## Import

```ts
import '@videojs/html/ui/controls';
import '@videojs/html/ui/controls-backdrop';
import '@videojs/html/ui/controls-content';
import '@videojs/html/ui/controls-group';
```

## Anatomy

Import the component and assemble its parts:

```html
<media-controls>
  <media-controls-backdrop></media-controls-backdrop>
  <media-controls-content>
    <media-controls-group></media-controls-group>
  </media-controls-content>
</media-controls>
```

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

```html
<media-controls visibility="always">
  <media-controls-content>...</media-controls-content>
</media-controls>
```

## Styling

`<media-controls>` is a state and context provider that also reflects the controls state data attributes. `<media-controls-content>` is the interactive controls surface and receives the same controls state data attributes.

`<media-controls-backdrop>` is an optional presentational sibling of `<media-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:

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

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

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

/* Fade transition */
media-controls-content {
  transition: opacity 0.25s;
}

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

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

## Accessibility

No ARIA role is applied to `<media-controls>` or `<media-controls-content>` — they provide state and layout, not a landmark. `<media-controls-backdrop>` is always hidden from assistive technology. `<media-controls-group>` automatically receives `role="group"` when an `aria-label` or `aria-labelledby` attribute is provided; otherwise no role is assigned.

## Examples

### Basic Usage

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>

    <media-controls>
      <media-controls-backdrop class="controls-backdrop"></media-controls-backdrop>
      <media-controls-content class="media-controls">
        <media-controls-group class="controls-group" aria-label="Playback controls">
          <media-play-button class="button media-play-button">
            <span class="paused">Play</span>
            <span class="playing">Pause</span>
          </media-play-button>
          <media-time class="time" type="current"></media-time>
        </media-controls-group>
      </media-controls-content>
    </media-controls>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.button .paused,
.button .playing {
  display: none;
}

.media-play-button[data-paused] .paused {
  display: inline;
}

.media-play-button:not([data-paused]) .playing {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/controls';
import '@videojs/html/ui/controls-backdrop';
import '@videojs/html/ui/controls-content';
import '@videojs/html/ui/controls-group';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/time';
```

## API Reference

### media-controls

Tracks controls visibility, reflects it as data attributes, and shares it with its descendant controls parts. Hiding the controls closes any popup open inside it.

#### Props

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

#### State

State is reflected as data attributes for CSS styling.

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

### media-controls-backdrop

Presentational backdrop that reflects its owning controls surface's state.

#### Data attributes

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

### media-controls-content

Interactive surface that reflects its owning controls state.

#### Data attributes

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

### media-controls-group

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

#### 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/html/reference/components/video-skin -->

# video-skin

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/html/reference/components/video-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the video preset ships.

## Import

```ts
import '@videojs/html/video/skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/video.js"></script>
```

## Anatomy

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

```html
<video-player>
  <video-skin>
    <video></video>
  </video-skin>
</video-player>
```

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

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

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. An `<img slot="thumbnail">` replaces it, so image attributes such as `crossorigin`, `loading`, and `fetchpriority` go on it.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<video-player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
  <video-skin class="html-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>
  </video-skin>
</video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/video/skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# video-neutral-skin

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/html/reference/components/video-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the video preset ships.

## Import

```ts
import '@videojs/html/video/neutral-skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/video-neutral.js"></script>
```

## Anatomy

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

```html
<video-player>
  <video-neutral-skin>
    <video></video>
  </video-neutral-skin>
</video-player>
```

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

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

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. An `<img slot="thumbnail">` replaces it, so image attributes such as `crossorigin`, `loading`, and `fetchpriority` go on it.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<video-player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
  <video-neutral-skin class="html-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>
  </video-neutral-skin>
</video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/video/neutral-skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# video-compat-skin

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/html/guides/customize-skins) to install and edit its source.

## Import

```ts
import '@videojs/html/video/compat-skin';
```

## Anatomy

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

```html
<video-player>
  <video-compat-skin>
    <video></video>
  </video-compat-skin>
</video-player>
```

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

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

## Thumbnail

The skin renders a storyboard preview image while scrubbing the time slider. An `<img slot="thumbnail">` replaces it, so image attributes such as `crossorigin`, `loading`, and `fetchpriority` go on it.

See [Show timeline thumbnail previews](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<video-player poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
  <video-compat-skin class="html-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>
  </video-compat-skin>
</video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/video/compat-skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# audio-skin

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/html/reference/components/audio-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the audio preset ships.

## Import

```ts
import '@videojs/html/audio/skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/audio.js"></script>
```

## Anatomy

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

```html
<audio-player>
  <audio-skin>
    <audio></audio>
  </audio-skin>
</audio-player>
```

## 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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<audio-player>
  <audio-skin class="html-audio-skin-basic">
    <audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossorigin="anonymous"></audio>
  </audio-skin>
</audio-player>
```

**index.css**

```css
.html-audio-skin-basic {
  display: block;
  width: 100%;
}
```

**index.ts**

```ts
import '@videojs/html/audio/player';
import '@videojs/html/audio/skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# audio-neutral-skin

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/html/reference/components/audio-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the audio preset ships.

## Import

```ts
import '@videojs/html/audio/neutral-skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/audio-neutral.js"></script>
```

## Anatomy

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

```html
<audio-player>
  <audio-neutral-skin>
    <audio></audio>
  </audio-neutral-skin>
</audio-player>
```

## 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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<audio-player>
  <audio-neutral-skin class="html-audio-neutral-skin-basic">
    <audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossorigin="anonymous"></audio>
  </audio-neutral-skin>
</audio-player>
```

**index.css**

```css
.html-audio-neutral-skin-basic {
  display: block;
  width: 100%;
}
```

**index.ts**

```ts
import '@videojs/html/audio/player';
import '@videojs/html/audio/neutral-skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# audio-compat-skin

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/html/guides/customize-skins) to install and edit its source.

## Import

```ts
import '@videojs/html/audio/compat-skin';
```

## Anatomy

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

```html
<audio-player>
  <audio-compat-skin>
    <audio></audio>
  </audio-compat-skin>
</audio-player>
```

## 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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<audio-player>
  <audio-compat-skin class="html-audio-compat-skin-basic">
    <audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" crossorigin="anonymous"></audio>
  </audio-compat-skin>
</audio-player>
```

**index.css**

```css
.html-audio-compat-skin-basic {
  display: block;
  width: 100%;
}
```

**index.ts**

```ts
import '@videojs/html/audio/player';
import '@videojs/html/audio/compat-skin';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-video-skin

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/html/reference/components/live-video-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the live video preset ships.

## Import

```ts
import '@videojs/html/live-video/skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-video.js"></script>
```

## Anatomy

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

```html
<live-video-player>
  <live-video-skin>
    <hls-video></hls-video>
  </live-video-skin>
</live-video-player>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/html/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/html/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-video-player>
  <live-video-skin class="html-live-video-skin-basic">
    <hls-video src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsinline crossorigin="anonymous"></hls-video>
  </live-video-skin>
</live-video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/live-video/player';
import '@videojs/html/live-video/skin';
import '@videojs/html/media/hls-video';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-video-neutral-skin

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/html/reference/components/live-video-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the live video preset ships.

## Import

```ts
import '@videojs/html/live-video/neutral-skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-video-neutral.js"></script>
```

## Anatomy

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

```html
<live-video-player>
  <live-video-neutral-skin>
    <hls-video></hls-video>
  </live-video-neutral-skin>
</live-video-player>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/html/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/html/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-video-player>
  <live-video-neutral-skin class="html-live-video-neutral-skin-basic">
    <hls-video src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsinline crossorigin="anonymous"></hls-video>
  </live-video-neutral-skin>
</live-video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/live-video/player';
import '@videojs/html/live-video/neutral-skin';
import '@videojs/html/media/hls-video';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-video-compat-skin

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/html/guides/customize-skins) to install and edit its source.

## Import

```ts
import '@videojs/html/live-video/compat-skin';
```

## Anatomy

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

```html
<live-video-player>
  <live-video-compat-skin>
    <hls-video></hls-video>
  </live-video-compat-skin>
</live-video-player>
```

This uses the lightweight [HLS video element](https://videojs.org/docs/framework/html/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/html/guides/live-streams).

## Poster

The skin renders a poster image before playback starts. An element with `slot="poster"` replaces it.

See [Add a poster and loading placeholder](https://videojs.org/docs/framework/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-video-player>
  <live-video-compat-skin class="html-live-video-compat-skin-basic">
    <hls-video src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" playsinline crossorigin="anonymous"></hls-video>
  </live-video-compat-skin>
</live-video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/live-video/player';
import '@videojs/html/live-video/compat-skin';
import '@videojs/html/media/hls-video';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-audio-skin

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/html/reference/components/live-audio-neutral-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the live audio preset ships.

## Import

```ts
import '@videojs/html/live-audio/skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-audio.js"></script>
```

## Anatomy

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

```html
<live-audio-player>
  <live-audio-skin>
    <mux-audio></mux-audio>
  </live-audio-skin>
</live-audio-player>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/html/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/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-audio-player>
  <live-audio-skin class="html-live-audio-skin-basic">
    <mux-audio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossorigin="anonymous"></mux-audio>
  </live-audio-skin>
</live-audio-player>
```

**index.css**

```css
.html-live-audio-skin-basic {
  display: block;
  width: 100%;
}
```

**index.ts**

```ts
import '@videojs/html/live-audio/player';
import '@videojs/html/live-audio/skin';
import '@videojs/html/media/mux-audio';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-audio-neutral-skin

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/html/reference/components/live-audio-skin) is the same preset’s other variant. See [Skins](https://videojs.org/docs/framework/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the live audio preset ships.

## Import

```ts
import '@videojs/html/live-audio/neutral-skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/live-audio-neutral.js"></script>
```

## Anatomy

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

```html
<live-audio-player>
  <live-audio-neutral-skin>
    <mux-audio></mux-audio>
  </live-audio-neutral-skin>
</live-audio-player>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/html/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/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-audio-player>
  <live-audio-neutral-skin class="html-live-audio-neutral-skin-basic">
    <mux-audio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossorigin="anonymous"></mux-audio>
  </live-audio-neutral-skin>
</live-audio-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/live-audio/player';
import '@videojs/html/live-audio/neutral-skin';
import '@videojs/html/media/mux-audio';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# live-audio-compat-skin

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/html/guides/customize-skins) to install and edit its source.

## Import

```ts
import '@videojs/html/live-audio/compat-skin';
```

## Anatomy

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

```html
<live-audio-player>
  <live-audio-compat-skin>
    <mux-audio></mux-audio>
  </live-audio-compat-skin>
</live-audio-player>
```

This uses the [Mux audio element](https://videojs.org/docs/framework/html/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/html/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/html/guides/customize-skins#style-a-packaged-skin) documents the properties. For deeper changes, the Video.js registry provides the skin files.

## Examples

### Basic Usage

**index.html**

```html
<live-audio-player>
  <live-audio-compat-skin class="html-live-audio-compat-skin-basic">
    <mux-audio src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" crossorigin="anonymous"></mux-audio>
  </live-audio-compat-skin>
</live-audio-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/live-audio/player';
import '@videojs/html/live-audio/compat-skin';
import '@videojs/html/media/mux-audio';
```

## 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=html#choose-how-to-install): Add editable skin source and build a working React or HTML player

---

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

# background-video-skin

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/html/guides/skins) for how packaged skins work and [Presets](https://videojs.org/docs/framework/html/guides/presets) for what the background preset ships.

## Import

```ts
import '@videojs/html/background/skin';
```

The import registers the skin and every UI element it composes. The [CDN](https://videojs.org/docs/framework/html/guides/cdn) player bundle registers this skin together with its player:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/background.js"></script>
```

## Anatomy

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

```html
<background-video-player>
  <background-video-skin>
    <background-video></background-video>
  </background-video-skin>
</background-video-player>
```

## 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/html/guides/customize-skins#style-a-packaged-skin) documents the properties.

## Examples

### Basic Usage

**index.html**

```html
<background-video-player>
  <background-video-skin class="html-background-video-skin-basic">
    <background-video src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"></background-video>
  </background-video-skin>
</background-video-player>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/background/player';
import '@videojs/html/background/skin';
import '@videojs/html/background/video';
```

## 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=html) 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/html/guides/background-video) to compose the media directly, then add only the UI your use case needs.

---

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

# audio

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

## Import

The media component is the browser’s native `<audio>`. Import the audio player registration when it should provide media to Video.js:

```ts
import '@videojs/html/audio/player';
```

## Anatomy

```html
<audio>
  <source />
</audio>
```

## Use with a player

Place a native `<audio>` anywhere inside `<audio-player>`. It becomes that player’s media provider automatically.

## 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/html/guides/media-sources) when you need an HLS, Mux, Spotify, or other playback adapter.

`<audio>` is the native element itself. Set its attributes and properties, listen for native media events, and access it through an `HTMLAudioElement` reference.

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.

**index.html**

```html
<audio-player>
  <media-container class="html-audio-basic">
    <audio class="html-audio-basic__media" controls preload="metadata">
      <source src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/audio.m4a" />
    </audio>
  </media-container>
</audio-player>
```

**index.css**

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

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

**index.ts**

```ts
import '@videojs/html/audio/player';
import '@videojs/html/ui/container';
```

---

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

# background-video

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.

`<background-video>` renders a `<video>` inside shadow DOM and fills the box you give the component. Use the opt-out attributes in the [API reference](https://videojs.org/docs/framework/html/reference/components/background-video#api-reference) to change its playback defaults.

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

## Import

```ts
import '@videojs/html/media/background-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/background-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<div class="container">
  <background-video src="https://stream.mux.com/601n4w1fq88NJiVpzvrQQeQfNnnjjfKMIN7dCGAEarTs/highest.mp4"></background-video>
</div>
```

**index.css**

```css
.container {
  display: grid;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/media/background-video';
```

## API Reference

### Attributes

| Attribute | Description |
| --- | --- |
| `src` | URL of a video the browser can play directly, such as an MP4 or WebM file. |
| `nomuted` | Opt out of muted playback. By default the video is muted. |
| `noloop` | Opt out of looped playback. By default the video loops. |
| `noautoplay` | Opt out of autoplay. By default the video autoplays. |

### CSS Custom Properties

| Variable | Default | Description |
| --- | --- | --- |
| `--media-object-fit` | `inherit` | Controls how the video fits its container. |
| `--media-object-position` | `50% 50%` | Controls the position of the video within its container. |

---

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

# cloudflare-video

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/html/guides/skins) like any other media component; set `controls` to use Cloudflare’s UI instead.

## Import

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

```ts
import '@videojs/html/media/cloudflare-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/cloudflare-video.js"></script>
```

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

```html
<cloudflare-video src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4"></cloudflare-video>
```

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

**index.html**

```html
<cloudflare-video class="cloudflare-video" src="https://watch.videodelivery.net/bfbd585059e33391d67b0f1d15fe6ea4" controls></cloudflare-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/cloudflare-video';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `loop` | `boolean` | `false` |
| `muted` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `defaultMuted` | `boolean` | `false` | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `{ play(): Promise<void> \| void; pause(): void; addEventListener(type: string, listener: ((event: Event) => void)): void; removeEventListener(type: string, listener: ((event: Event) => void)): void; src: string; currentTime: number; volume: number; muted: boolean; playbackRate: number; loop: boolean; autoplay: boolean; controls: boolean; preload: string; poster: string; paused: boolean; ended: boolean; seeking: boolean; duration: number; buffered: TimeRanges; played: TimeRanges; videoWidth: number; videoHeight: number } \| null` | — | Read-only. Underlying Stream SDK player instance (null until the SDK loads). |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `playbackRate` | `number` | — | |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `source` | `{ src?: string; engine?: CloudflareSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed parameters under `engine.cloudflare`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: the SDK exposes no track API, and the embed owns the track picked by `defaultTextTrack`. |
| `videoHeight` | `number` | — | Read-only. |
| `videoWidth` | `number` | — | Read-only. |
| `volume` | `number` | — | |

### 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/html/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.

```ts
const video = document.querySelector('cloudflare-video');
video.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'`). |

### Methods

Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `error`, `loadedmetadata`, `loadstart`, `volumechange`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `loadcomplete` | |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

---

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

# dash-video

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

```ts
import '@videojs/html/media/dash-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/dash-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <dash-video src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoplay muted playsinline loop></dash-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/dash-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `engine` | `dashjs.MediaPlayerClass` | — | Read-only. Underlying playback engine — the dash.js `MediaPlayerClass` instance. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. |
| `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` | `''` | |
| `streamType` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
| `targetLiveWindow` | `number` | — | Read-only. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `disableRemotePlayback`, `duration`, `ended`, `error`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `preload`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# hls-audio

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/html/reference/components/hls-video).

## Import

```ts
import '@videojs/html/media/hls-audio';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/hls-audio.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<hls-audio class="hls-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" controls></hls-audio>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/hls-audio';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<audio>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `alternativeMediaSuggestion` | `string \| undefined` | — | Read-only. A complete sentence naming the Media to reach for when this one can't play a source. Appended to the copy this adapter logs. Empty here, and overridden the same way as on the video adapter — see its note. `hls-audio` has no better-equipped sibling of its own; the Mux audio Media built on this engine does, and points at the hls.js-backed one. |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `disableRemotePlayback` | `boolean` | `false` | |
| `engine` | `{ state: { [K in keyof S]-?: Signal<S[K]> }; context: { [K in keyof C]-?: Signal<C[K]> }; destroy(): Promise<void> }` | — | Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `{ code: number; message: string; data?: unknown } \| null` | — | Read-only. The current fatal error, or `null`. Only *fatal* conditions appear here — the engine reports non-fatal ones too, which stay in `engine.state.errors`. Resets per source. Fires `'error'` when set. |
| `liveEdgeStart` | `number` | — | Read-only. |
| `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` | `''` | |
| `streamType` | `MediaStreamType` | — | Current stream type (`'on-demand'`, `'live'`, or `'unknown'`). Defaults to `'unknown'`; detecting hosts update it automatically, and consumers can set it to override detection. |
| `targetLiveWindow` | `number` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `volume`.

### Methods

Supports these media methods. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `addTextTrack`, `canPlayType`, `load`, `pause`, `play`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `error` | Fired when a fatal condition is reported. Read `error` for it. |
| `sourcechange` | Fired when `source` changes. Read `source` for the new value. |

---

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

# hls-background-video

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

`<hls-background-video>` 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/html/guides/background-video) for layout, poster, accessibility, and source-choice guidance.

## Import

```ts
import '@videojs/html/media/hls-background-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/hls-background-video.js"></script>
```

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

```html
<hls-background-video
  src="https://media.example.com/hero.m3u8"
  crossorigin
></hls-background-video>
```

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 |
| `error` | Fatal SPF media error for the current source, or `null` |
| `video` | Inner native `<video>` element |

The element also fires an `error` event when `error` becomes fatal. The inner video’s own `error` can remain `null` because SPF, rather than the browser, rejected the source.

## Styling

| Custom property | Default | Description |
| --- | --- | --- |
| `--media-object-fit` | `inherit` | How the video fits its box |
| `--media-object-position` | `50% 50%` | Position of the video within its box |

Set an explicit size on the custom element or an author-owned wrapper.

---

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

# hls-video

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/html/reference/components/hlsjs-video) is the larger, more compatible alternative.

## Import

```ts
import '@videojs/html/media/hls-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/hls-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <hls-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hls-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/hls-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'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. |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `alternativeMediaSuggestion` | `string \| undefined` | — | Read-only. A complete sentence naming the Media to reach for when this one can't play a source — `Try the hls.js-backed Mux media instead: import the hls-js flavor in place of the spf one.` Appended to the copy this adapter surfaces, and to the notices it logs. Name the flavor, not an import path: a Media is reached through several packages, each with its own counterpart. Empty here: `hls-video` has no better-equipped sibling to point at. A Media that does (a Mux Video built on this engine, whose hls.js-backed counterpart plays MPEG-TS and DRM) overrides this static, and its copy gains the second sentence with no other change. |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `disableRemotePlayback` | `boolean` | `false` | |
| `engine` | `{ state: { [K in keyof S]-?: Signal<S[K]> }; context: { [K in keyof C]-?: Signal<C[K]> }; destroy(): Promise<void> }` | — | Read-only. Underlying playback engine — the low-level SPF reactive composition that drives playback. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `{ code: number; message: string; data?: unknown } \| null` | — | Read-only. The current fatal error, or `null`. Only *fatal* conditions appear here — the engine reports non-fatal ones too (they stay in `engine.state.errors`), and promoting them would tell a consumer playback had failed when it hadn't. Resets per source. Fires `'error'` when set. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the live-edge window — playback at `currentTime >= liveEdgeStart` counts as "at the live edge" (the same target the engine's `seekToLiveEdge` seeks to: window end − HOLD-BACK). `NaN` when the stream isn't live or nothing is resolved yet. Derived at read time from the engine's live window — no change event; re-read on `timeupdate`/`progress` (as the store's live feature does). |
| `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. |
| `targetLiveWindow` | `number` | — | Read-only. The target live window: `NaN` for on-demand (or unknown), `0` for standard sliding-window live, `Infinity` for DVR (`#EXT-X-PLAYLIST-TYPE:EVENT`). Fires `targetlivewindowchange` on change. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `error` | Fired when a fatal condition is reported. Read `error` for it. |
| `sourcechange` | Fired when `source` changes. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# hlsjs-video

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/html/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/html/reference/components/native-hls-video).

## Import

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

```ts
import '@videojs/html/media/hlsjs-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/hlsjs-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `audioRenditions` | `AudioRenditionListLike \| undefined` | — | Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `audioTracks` | `AudioTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live. |
| `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'`). |
| `targetLiveWindow` | `number` | — | Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate). |
| `videoRenditions` | `VideoRenditionListLike \| undefined` | — | Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `videoTracks` | `VideoTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

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

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# mux-audio

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

```ts
import '@videojs/html/media/mux-audio';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/mux-audio.js"></script>
```

## 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/html/guides/mux-data) and [Google Cast](https://videojs.org/docs/framework/html/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
```

```html
<mux-audio src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-audio>
<mux-data player-software-name="mux-audio"></mux-data>
<google-cast></google-cast>
```

Register the elements by importing `@videojs/html/extensions/mux-data` and `@videojs/html/extensions/google-cast`.

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

## Examples

### Basic Usage

**index.html**

```html
<mux-audio class="mux-audio" src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" crossorigin="anonymous" controls></mux-audio>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/mux-audio';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<audio>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `audioRenditions` | `AudioRenditionListLike \| undefined` | — | Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `audioTracks` | `AudioTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `contentData` | `{ readonly [key: string]: MediaContentValue; title?: string; poster?: string; storyboard?: string }` | — | Read-only. What `source` says about its content. `poster` and `storyboard` are image URLs it describes rather than plays, from its `poster` and `storyboard` params; a key is absent when the URL can't be built — no playback ID, or signed playback without a matching image token. `title` and the rest come from the metadata Mux publishes for the asset, which loads with the source, so they arrive later than the URLs and are absent until then. The same object is handed back until something in it changes, and `contentdatachange` announces it when it does. Nothing here is applied for you, apart from the thumbnail track `<mux-video>` adds from `storyboard` (and drops for live streams). |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `MediaError \| null` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live. |
| `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'`). |
| `targetLiveWindow` | `number` | — | Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate). |
| `videoRenditions` | `VideoRenditionListLike \| undefined` | — | Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `videoTracks` | `VideoTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |

Also exposes these properties from the native media API. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `volume`.

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

### Methods

Supports these media methods. See [HTMLAudioElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement) for details: `addTextTrack`, `canPlayType`, `load`, `pause`, `play`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `durationchange`, `emptied`, `ended`, `error`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `contentdatachange` | Fired when `contentData` changes: the derived URLs with `source`, and the metadata once it loads. Read `contentData` for the new value. |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

---

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

# mux-background-video

Mux-specific name for the HLS background video component

`<mux-background-video>` is the Mux-specific name for [`<hls-background-video>`](https://videojs.org/docs/framework/html/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/html/guides/background-video) to compare the background-video options.

## Import

```ts
import '@videojs/html/media/mux-background-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/mux-background-video.js"></script>
```

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

```html
<mux-background-video
  src="https://stream.mux.com/PLAYBACK_ID.m3u8?max_resolution=720p"
  crossorigin
></mux-background-video>
```

`<mux-background-video>` 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, fixed playback behavior, and CSS custom properties are identical to [`<hls-background-video>`](https://videojs.org/docs/framework/html/reference/components/hls-background-video).

---

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

# mux-video

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

```ts
import '@videojs/html/media/mux-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/mux-video.js"></script>
```

## Load a source

`<mux-video>` takes Mux content two ways: a stream URL through `src`, or a structured `source` object.

```html
<mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"></mux-video>
```

The `source` object 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`.

```ts
const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  customDomain: 'media.example.com',
  playback: { maxResolution: '1080p' },
};
```

`<mux-video>` 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.

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:

```ts
const video = document.querySelector('mux-video')!;
video.source = {
  playbackId: 'BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM',
  poster: { time: 2, width: 1280 },
  storyboard: { format: 'webp' },
};
```

For declarative HTML, `poster-time="2"` reflects to `source.poster.time` after the `src` attribute is parsed.

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/html/reference/components/thumbnail) then fetches the sprite sheets its cues point at the same way:

```html
<mux-video
  src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8"
  crossorigin="anonymous"
></mux-video>
```

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

```ts
const video = document.querySelector('mux-video')!;
video.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/html/guides/mux-data) and [Google Cast](https://videojs.org/docs/framework/html/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
```

```html
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/media/mux-video';
  import '@videojs/html/extensions/mux-data';
  import '@videojs/html/extensions/google-cast';
</script>

<video-player>
  <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" playsinline></mux-video>
  <mux-data player-software-name="mux-video"></mux-data>
  <google-cast></google-cast>
</video-player>
```

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

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <mux-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop crossorigin="anonymous"></mux-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/mux-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `audioRenditions` | `AudioRenditionListLike \| undefined` | — | Read-only. Selectable audio variants, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `audioTracks` | `AudioTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `contentData` | `{ readonly [key: string]: MediaContentValue; title?: string; poster?: string; storyboard?: string }` | — | Read-only. What `source` says about its content. `poster` and `storyboard` are image URLs it describes rather than plays, from its `poster` and `storyboard` params; a key is absent when the URL can't be built — no playback ID, or signed playback without a matching image token. `title` and the rest come from the metadata Mux publishes for the asset, which loads with the source, so they arrive later than the URLs and are absent until then. The same object is handed back until something in it changes, and `contentdatachange` announces it when it does. Nothing here is applied for you, apart from the thumbnail track `<mux-video>` adds from `storyboard` (and drops for live streams). |
| `disableRemotePlayback` | `unknown` | `false` | Whether remote playback (AirPlay, Google Cast) is disabled for this media. |
| `engine` | `Hls \| null` | — | Read-only. Underlying playback engine — the hls.js `Hls` instance when playing via MSE, otherwise `null`. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Presentation time marking the start of the Live Edge Window. Derived from the delegate on every read; `NaN` when no delegate is attached or the stream is not live. |
| `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'`). |
| `targetLiveWindow` | `number` | — | Read-only. Seekable range size for live content. `0` for standard live, `Infinity` for DVR, `NaN` for on-demand or unknown. Fires `targetlivewindowchange` when the value changes (bridged from the delegate). |
| `videoRenditions` | `VideoRenditionListLike \| undefined` | — | Read-only. Selectable quality levels, populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `videoTracks` | `VideoTrackListLike \| undefined` | — | Read-only. Populated only while the hls.js (MSE) engine is active; otherwise `undefined`. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

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

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `contentdatachange` | Fired when `contentData` changes: the derived URLs with `source`, and the metadata once it loads. Read `contentData` for the new value. |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# native-hls-video

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/html/reference/components/hlsjs-video) instead.

## Import

```ts
import '@videojs/html/media/native-hls-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/native-hls-video.js"></script>
```

## Examples

### Basic Usage

**index.html**

```html
<media-container class="media-container">
  <native-hls-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></native-hls-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/native-hls-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` | Current stream type (`'on-demand'` / `'live'` / `'unknown'`). |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `engine` | `null` | — | Read-only. Underlying playback engine — always `null`. Native HLS has no JS engine; the browser handles playback directly. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. Playback time where the live edge begins. Calculated from the newest available time and the playlist's live-edge offset. `NaN` when the stream is not live or the offset is unavailable. |
| `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'`). |
| `targetLiveWindow` | `number` | — | Read-only. Describes the kind of live window available. `0` for a sliding live window, `Infinity` for a live event with playback history, and `NaN` for on-demand or unknown. This value is not a duration. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `disableRemotePlayback`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

### 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/html/guides/media-sources) covers how engine options fit into a structured source.

```ts
const video = document.querySelector('native-hls-video');
video.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. |

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when the target live window changes. Read `targetLiveWindow` for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# shaka-video

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

```ts
import '@videojs/html/media/shaka-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/shaka-video.js"></script>
```

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

```html
<shaka-video src="https://example.com/manifest.mpd"></shaka-video>
```

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

```ts
const video = document.querySelector('shaka-video');
video.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.

```ts
const video = document.querySelector('shaka-video');
video.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

**index.html**

```html
<media-container class="media-container">
  <shaka-video src="https://dash.akamaized.net/akamai/streamroot/050714/Spring_4Ktest.mpd" autoplay muted playsinline loop></shaka-video>
</media-container>
```

**index.css**

```css
.media-container {
  position: relative;
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
}
```

**index.ts**

```ts
import '@videojs/html/ui/container';
import '@videojs/html/media/shaka-video';
```

## API Reference

### Attributes

Forwards these standard media attributes to the internal `<video>`. See the [MDN media element reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video): `autopictureinpicture`, `autoplay`, `controls`, `controlslist`, `crossorigin`, `disablepictureinpicture`, `disableremoteplayback`, `loading`, `loop`, `muted`, `playsinline`, `poster`, `preload`, `src`.

These Video.js-specific attributes configure media behavior:

| Attribute | Type | Default |
| --- | --- | --- |
| `stream-type` | `'on-demand' \| 'live' \| 'unknown'` | `'unknown'` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `contentData` | `MediaContentData \| undefined` | — | Read-only. |
| `engine` | `shaka.Player \| null` | — | Read-only. Underlying playback engine — the Shaka `Player` instance, or `null` when the browser cannot run it. An advanced escape hatch for direct engine access; normal playback is driven through this element's own properties and methods. |
| `error` | `unknown` | — | Read-only. The last playback failure Shaka could not recover from, or `null`. Shaka loads asynchronously, so a manifest that cannot be played fails after `src` was assigned rather than at the assignment; the `error` event is when to read this. A Shaka failure says more about what went wrong than the media element's own `error` does, so it wins while there is one; anything the element failed on by itself still reads through. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `liveEdgeStart` | `number` | — | Read-only. |
| `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'` | |
| `targetLiveWindow` | `number` | — | Read-only. |
| `webkitCurrentPlaybackTargetIsWireless` | `boolean \| undefined` | — | Read-only. |
| `webkitPresentationMode` | `WebKitPresentationMode \| undefined` | — | Read-only. |
| `webkitSetPresentationMode` | `((mode: WebKitPresentationMode) => void) \| undefined` | — | Read-only. |

Also exposes these properties from the native media API. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `autoplay`, `buffered`, `controls`, `crossOrigin`, `currentSrc`, `currentTime`, `defaultMuted`, `defaultPlaybackRate`, `disablePictureInPicture`, `disableRemotePlayback`, `duration`, `ended`, `loop`, `muted`, `paused`, `playbackRate`, `played`, `playsInline`, `poster`, `readyState`, `remote`, `seekable`, `seeking`, `textTracks`, `title`, `videoHeight`, `videoWidth`, `volume`.

### Methods

Supports these media methods. See [HTMLVideoElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement) for details: `addTextTrack`, `canPlayType`, `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Re-dispatches these standard media events from the internal media element: `abort`, `addtrack`, `canplay`, `canplaythrough`, `change`, `contentdatachange`, `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `leavepictureinpicture`, `loadeddata`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `removetrack`, `resize`, `seeked`, `seeking`, `stalled`, `suspend`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `error` | Fired when playback fails in a way Shaka could not recover from. Read `error` for the failure. |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |
| `streamtypechange` | Fired when the detected stream type changes. Read `streamType` for the new value. |
| `targetlivewindowchange` | Fired when `targetLiveWindow` changes. Read it for the new value. |

### CSS custom properties

| Variable | Description |
| --- | --- |
| `--media-video-border-radius` | Border radius of the video element. |
| `--media-object-fit` | Object fit for the video. |
| `--media-object-position` | Object position for the video. |
| `--media-caption-track-duration` | Duration of the caption track transition. |
| `--media-caption-track-delay` | Delay before the caption track transition. |
| `--media-caption-track-y` | Vertical offset of the caption track. |

---

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

# spotify-audio

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

```ts
import '@videojs/html/media/spotify-audio';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/spotify-audio.js"></script>
```

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

```html
<spotify-audio src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls></spotify-audio>
```

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

**index.html**

```html
<spotify-audio class="spotify-audio" src="https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5" controls></spotify-audio>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/spotify-audio';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `loop` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `{ iframeElement: HTMLIFrameElement; loadUri(uri: string): void; play(): void; resume(): void; pause(): void; togglePlay(): void; seek(seconds: number): void; destroy(): void; addListener(type: 'ready', listener: (() => void)): void; addListener(type: 'playback_update', listener: ((event: SpotifyPlaybackUpdateEvent) => void)): void } \| null` | — | Read-only. Underlying Spotify iframe API controller (null until the API loads). |
| `error` | `MediaError \| null` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `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` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: the embed exposes no captions or other text tracks. |

### 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/html/guides/media-sources) covers how engine options fit into a structured source.

```ts
const audio = document.querySelector('spotify-audio');
audio.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. |

### Methods

Supports these media methods: `load`, `pause`, `play`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `seeked`, `seeking`, `timeupdate`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `loadcomplete` | |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

---

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

# tiktok-video

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

```ts
import '@videojs/html/media/tiktok-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/tiktok-video.js"></script>
```

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

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

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

**index.html**

```html
<tiktok-video class="tiktok-video" src="https://www.tiktok.com/@_luwes/video/7527476667770522893" controls></tiktok-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/tiktok-video';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `loop` | `boolean` | `false` |
| `muted` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `defaultMuted` | `boolean` | `false` | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `Window \| null` | — | Read-only. The embed's window. TikTok publishes no player object; commands are posted to the frame. Null until rendered. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `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` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. Always empty: `closed_caption` is the embed's only say over captions. |

### 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/html/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.

```ts
const video = document.querySelector('tiktok-video');
video.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`. |

### Methods

Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `loadcomplete` | |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

---

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

# twitch-video

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/html/guides/skins) like any other media component; set `controls` to use Twitch’s UI instead.

## Import

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

```ts
import '@videojs/html/media/twitch-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/twitch-video.js"></script>
```

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

```html
<twitch-video src="https://www.twitch.tv/videos/106400740"></twitch-video>
```

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

```ts
const video = document.querySelector('twitch-video');
video.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

**index.html**

```html
<twitch-video class="twitch-video" src="https://www.twitch.tv/videos/106400740" controls></twitch-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/twitch-video';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `loop` | `boolean` | `false` |
| `muted` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `defaultMuted` | `boolean` | `false` | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `Window \| null` | — | Read-only. The embed's own window, which every command is posted to. Null until an embed is bound and in a document. |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `playbackRate` | `number` | — | |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `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` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. |
| `volume` | `number` | — | |

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

### Methods

Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `playing`, `progress`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `loadcomplete` | |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

---

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

# video

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

## Import

The media component is the browser’s native `<video>`. Import the video player registration when it should provide media to Video.js:

```ts
import '@videojs/html/video/player';
```

## Anatomy

```html
<video>
  <source />
  <track />
</video>
```

## Use with a player

Place a native `<video>` anywhere inside `<video-player>`. It becomes that player’s media provider automatically.

## 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/html/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>` is the native element itself. Set its attributes and properties, listen for native media events, and access it through an `HTMLVideoElement` reference.

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.

**index.html**

```html
<video-player>
  <media-container class="html-video-basic">
    <video class="html-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>
  </media-container>
</video-player>
```

**index.css**

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

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

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
```

---

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

# vimeo-video

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/html/guides/skins) like any other media component; set `controls` to use Vimeo’s UI instead.

## Import

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

```ts
import '@videojs/html/media/vimeo-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/vimeo-video.js"></script>
```

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

```html
<vimeo-video src="https://vimeo.com/76979871"></vimeo-video>
```

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

**index.html**

```html
<vimeo-video class="vimeo-video" src="https://vimeo.com/76979871" controls></vimeo-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/vimeo-video';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `disablepictureinpicture` | `boolean` | — |
| `loop` | `boolean` | `false` |
| `muted` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `contentData` | `{ title?: string \| null; poster?: string \| null; storyboard?: string \| null; readonly [key: string]: MediaContentValue }` | — | Read-only. Metadata Vimeo reports about the loaded video, keyed by what it is — `title` for now. Unlike a Mux source, none of it can be derived from `src`; the embed has to report it, so the key is absent until then and empties again across a source change. `contentdatachange` announces both. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `defaultMuted` | `boolean` | `false` | |
| `disablePictureInPicture` | `boolean` | — | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `VimeoPlayer \| null` | — | Read-only. Underlying `@vimeo/player` instance. Null until an embed URL can be resolved, which may be after `attach()`. |
| `error` | `{ code: number; message: string } \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `isPictureInPicture` | `boolean` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `playbackRate` | `number` | — | |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `source` | `{ src?: string; engine?: VimeoSourceEngineConfig } \| null` | `null` | Structured source: `src` plus embed options under `engine.vimeo`. Replacing it re-derives `src`. |
| `src` | `string` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. |
| `videoHeight` | `number` | — | Read-only. |
| `videoWidth` | `number` | — | Read-only. |
| `volume` | `number` | — | |

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

```ts
const video = document.querySelector('vimeo-video');
video.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. |

### Methods

Supports these media methods: `exitFullscreen`, `exitPictureInPicture`, `load`, `pause`, `play`, `requestFullscreen`, `requestPictureInPicture`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `enterpictureinpicture`, `error`, `leavepictureinpicture`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `resize`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `contentdatachange` | Fired when the embed reports a title and when that title is cleared. Read `contentData` for the new value. |
| `fullscreenchange` | |
| `loadcomplete` | |
| `sourcechange` | Fired when `source` changes, either directly or by resolving a new `src`. Read `source` for the new value. |

---

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

# wistia-video

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

`<wistia-video>` 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
```

```ts
import '@videojs/html/media/wistia-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/wistia-video.js"></script>
```

## Load a source

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

```html
<wistia-video src="https://example.wistia.com/medias/abcde12345?wtime=30"></wistia-video>
```

## Wistia options

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

```ts
const video = document.querySelector('wistia-video');
video.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.

## Examples

### Basic Usage

**index.html**

```html
<wistia-video class="wistia-video" src="https://wesleyluyten.wistia.com/medias/oifkgmxnkb" controls></wistia-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/wistia-video';
```

---

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

# youtube-video

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/html/guides/skins) like any other media component; set `controls` to use YouTube’s UI instead.

## Import

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

```ts
import '@videojs/html/media/youtube-video';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/media/youtube-video.js"></script>
```

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

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

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

**index.html**

```html
<youtube-video class="youtube-video" src="https://www.youtube.com/watch?v=aqz-KE-bpKQ" controls></youtube-video>
```

**index.css**

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

**index.ts**

```ts
import '@videojs/html/media/youtube-video';
```

## API Reference

### Attributes

These attributes configure the embedded media adapter:

| Attribute | Type | Default |
| --- | --- | --- |
| `autoplay` | `boolean` | `false` |
| `controls` | `boolean` | `false` |
| `loop` | `boolean` | `false` |
| `muted` | `boolean` | `false` |
| `playsinline` | `boolean` | `true` |
| `poster` | `string` | `''` |
| `preload` | `MediaPreloadType` | `'metadata'` |
| `src` | `string` | `''` |

### Properties

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `autoplay` | `boolean` | `false` | |
| `buffered` | `TimeRangeLike` | — | Read-only. |
| `controls` | `boolean` | `false` | |
| `currentSrc` | `string` | — | Read-only. |
| `currentTime` | `number` | — | |
| `defaultMuted` | `boolean` | `false` | |
| `duration` | `number` | — | Read-only. |
| `ended` | `boolean` | — | Read-only. |
| `engine` | `{ playVideo(): void; pauseVideo(): void; seekTo(seconds: number, allowSeekAhead: boolean): void; mute(): void; unMute(): void; isMuted(): boolean; setVolume(volume: number): void; getVolume(): number; getDuration(): number; getCurrentTime(): number; getPlaybackRate(): number; setPlaybackRate(rate: number): void; getVideoLoadedFraction(): number; getPlayerState(): number; loadVideoById(options: { videoId: string; startSeconds?: number }): void; cueVideoById(options: { videoId: string; startSeconds?: number }): void; loadPlaylist(options: { list: string; listType?: string }): void; cuePlaylist(options: { list: string; listType?: string }): void; stopVideo(): void; getOption(module: string, option: string): unknown; setOption(module: string, option: string, value: unknown): void; addEventListener(type: string, listener: ((event: { data: number }) => void)): void; destroy(): void } \| null` | — | Read-only. Underlying YouTube iframe API player instance (null until the API loads). |
| `error` | `MediaError \| null` | — | Read-only. |
| `isFullscreen` | `boolean` | — | Read-only. |
| `loop` | `boolean` | `false` | |
| `muted` | `boolean` | `false` | |
| `paused` | `boolean` | — | Read-only. |
| `playbackRate` | `number` | — | |
| `played` | `{ length: number; start(index: number): number; end(index: number): number }` | — | Read-only. |
| `playsInline` | `boolean` | `true` | |
| `poster` | `string` | `''` | |
| `preload` | `MediaPreloadType` | `'metadata'` | |
| `readyState` | `number` | — | Read-only. |
| `seekable` | `TimeRangeLike` | — | Read-only. |
| `seeking` | `boolean` | — | Read-only. |
| `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` | `''` | |
| `textTracks` | `TextTrackListLike` | — | Read-only. |
| `volume` | `number` | — | |

### 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/html/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.

```ts
const video = document.querySelector('youtube-video');
video.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. |

### Methods

Supports these media methods: `exitFullscreen`, `load`, `pause`, `play`, `requestFullscreen`.

### Events

Implements these standard media events through the embedded player: `durationchange`, `emptied`, `ended`, `error`, `loadedmetadata`, `loadstart`, `pause`, `play`, `playing`, `progress`, `ratechange`, `seeked`, `seeking`, `timeupdate`, `volumechange`, `waiting`.

Also emits these Video.js-specific events:

| Event | Description |
| --- | --- |
| `loadcomplete` | |
| `sourcechange` | |

---

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

# google-cast

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

Adds the [Google Cast extension](https://videojs.org/docs/framework/html/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/html/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/html/guides/casting) for the complete setup.

## Import

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

```ts
import '@videojs/html/extensions/google-cast';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/extensions/google-cast.js"></script>
```

## Anatomy

```html
<google-cast></google-cast>
```

## Options

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

`customData` takes an object, so it’s a property only, with no matching attribute. Set it on the element, typed as the `GoogleCastExtension` class that `@videojs/html/extensions/google-cast` exports.

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/html/guides/casting): Add remote playback to a player
- [CastButton component reference](https://videojs.org/docs/framework/html/reference/components/cast-button)
- [Remote Playback feature reference](https://videojs.org/docs/framework/html/reference/api/feature-remote-playback)

---

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

# mux-data

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/html/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/html/guides/mux-data) for how monitoring works.

## Import

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

```ts
import '@videojs/html/extensions/mux-data';
```

Or load it from the [CDN](https://videojs.org/docs/framework/html/guides/cdn):

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@videojs/cdn@10.0.1/extensions/mux-data.js"></script>
```

## Anatomy

```html
<mux-data></mux-data>
```

## Options

| Attribute | Property | Description |
| --- | --- | --- |
| `env-key` | `envKey` | Mux Data environment key the beacons are sent to. Optional for Mux-hosted playback |
| — | `metadata` | Mux Data metadata for the view |
| `player-software-name` | `playerSoftwareName` | Player name reported to Mux Data |
| `player-software-version` | `playerSoftwareVersion` | Player version reported to Mux Data. Defaults to the Video.js version |
| `player-init-time` | `playerInitTime` | Epoch milliseconds the player was initialized. Defaults to when the player was created |
| `beacon-collection-domain` | `beaconCollectionDomain` | Custom domain the beacons are sent to |
| `disable-cookies` | `disableCookies` | Stops the SDK from setting cookies |
| `debug` | `debug` | Turns on SDK debug logging |
| — | `MuxDataSdk` | SDK used for monitoring. Set it to `undefined` to switch monitoring off |

`metadata` and `MuxDataSdk` take objects, so they’re properties only, with no matching attribute. Set them on the element, typed as the `MuxDataExtension` class that `@videojs/html/extensions/mux-data` exports.

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/html/guides/mux-data): How monitoring works
- [Mux video reference](https://videojs.org/docs/framework/html/reference/components/mux-video)
- [Mux audio reference](https://videojs.org/docs/framework/html/reference/components/mux-audio)

---

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

# media-play-button

Accessible play/pause button with keyboard support and customizable rendering

## Import

```ts
import '@videojs/html/ui/play-button';
```

## Anatomy

```html
<media-play-button></media-play-button>
```

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

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

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

/* Ended */
media-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 */
media-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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline></video>
    <media-play-button class="media-play-button">
      <span class="paused">Play</span>
      <span class="playing">Pause</span>
      <span class="ended">Replay</span>
    </media-play-button>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}

.media-play-button .paused {
  display: none;
}
.media-play-button .playing {
  display: none;
}
.media-play-button .ended {
  display: none;
}
.media-play-button[data-paused]:not([data-ended]) .paused {
  display: inline;
}
.media-play-button:not([data-paused]) .playing {
  display: inline;
}
.media-play-button[data-ended] .ended {
  display: inline;
}
.media-play-button[data-ended] .paused {
  display: none;
}
.media-play-button[data-ended] .playing {
  display: none;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/mute-button -->

# media-mute-button

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

## Import

```ts
import '@videojs/html/ui/mute-button';
```

## Anatomy

```html
<media-mute-button></media-mute-button>
```

## 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 element receives the native `hidden` attribute. 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:

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

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

```css
media-mute-button[data-volume-level="off"] .icon-off { display: inline; }
media-mute-button[data-volume-level="low"] .icon-low { display: inline; }
media-mute-button[data-volume-level="medium"] .icon-medium { display: inline; }
media-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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-mute-button class="media-mute-button">
      <span class="muted">Unmute</span>
      <span class="unmuted">Mute</span>
    </media-mute-button>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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-mute-button .muted {
  display: none;
}
.media-mute-button .unmuted {
  display: none;
}
.media-mute-button[data-muted] .muted {
  display: inline;
}
.media-mute-button:not([data-muted]) .unmuted {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
```

### Volume Levels

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-mute-button class="media-mute-button">
      <span class="level-off">Off</span>
      <span class="level-low">Low</span>
      <span class="level-medium">Medium</span>
      <span class="level-high">High</span>
    </media-mute-button>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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-mute-button .level-off,
.media-mute-button .level-low,
.media-mute-button .level-medium,
.media-mute-button .level-high {
  display: none;
}

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

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/seek-button -->

# media-seek-button

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

## Import

```ts
import '@videojs/html/ui/seek-button';
```

## Anatomy

```html
<media-seek-button></media-seek-button>
```

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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="buttons">
      <media-seek-button seconds="-5" class="media-seek-button">
        <span class="backward">&#9194; 5s</span>
      </media-seek-button>
      <media-seek-button seconds="10" class="media-seek-button">
        <span class="forward">10s &#9193;</span>
      </media-seek-button>
    </div>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}

.media-seek-button .backward {
  display: none;
}
.media-seek-button .forward {
  display: none;
}
.media-seek-button[data-direction="backward"] .backward {
  display: inline;
}
.media-seek-button[data-direction="forward"] .forward {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/seek-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/fullscreen-button -->

# media-fullscreen-button

Accessible fullscreen toggle button with keyboard support and state reflection

## Import

```ts
import '@videojs/html/ui/fullscreen-button';
```

## Anatomy

```html
<media-fullscreen-button></media-fullscreen-button>
```

## 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"`) — applies the native HTML `hidden` attribute on the custom element.

## Styling

You can style the button based on fullscreen state:

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

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

The button remains hidden until fullscreen is available.

The element receives the native `hidden` attribute. 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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-fullscreen-button class="media-fullscreen-button">
      <span class="fullscreen">Exit Fullscreen</span>
      <span class="not-fullscreen">Fullscreen</span>
    </media-fullscreen-button>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.media-fullscreen-button .fullscreen {
  display: none;
}
.media-fullscreen-button .not-fullscreen {
  display: none;
}
.media-fullscreen-button[data-fullscreen] .fullscreen {
  display: inline;
}
.media-fullscreen-button:not([data-fullscreen]) .not-fullscreen {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/fullscreen-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/pip-button -->

# media-pip-button

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

## Import

```ts
import '@videojs/html/ui/pip-button';
```

## Anatomy

```html
<media-pip-button></media-pip-button>
```

## 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"`) — applies the native HTML `hidden` attribute on the custom element.

## Styling

You can style the button based on PiP state:

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

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

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

The element receives the native `hidden` attribute. 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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-pip-button class="media-pip-button">
      <span class="pip">Exit PiP</span>
      <span class="not-pip">Enter PiP</span>
    </media-pip-button>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.media-pip-button .pip {
  display: none;
}
.media-pip-button .not-pip {
  display: none;
}
.media-pip-button[data-pip] .pip {
  display: inline;
}
.media-pip-button:not([data-pip]) .not-pip {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/pip-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/captions-button -->

# media-captions-button

Accessible captions toggle button with availability detection and state reflection

## Import

```ts
import '@videojs/html/ui/captions-button';
```

## Anatomy

```html
<media-captions-button></media-captions-button>
```

## 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 element receives the native `hidden` attribute. The raw state remains available as `data-availability`.

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

When `menu-for` is set to a menu’s `id` and multiple caption or subtitle tracks are available, activation opens the linked captions menu instead of toggling captions directly.

## Styling

Style the button based on active state:

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

Style an explicitly disabled, available button:

```css
media-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

**index.html**

```html
<video-player class="video-player">
  <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>
    <media-captions-button class="media-captions-button">
      <span class="active">Captions Off</span>
      <span class="inactive">Captions On</span>
    </media-captions-button>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}

.media-captions-button .active {
  display: none;
}
.media-captions-button .inactive {
  display: none;
}
.media-captions-button[data-active] .active {
  display: inline;
}
.media-captions-button:not([data-active]) .inactive {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/captions-button';
```

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

### State

State is reflected as data attributes for CSS styling.

| 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/html/reference/components/playback-rate-button -->

# media-playback-rate-button

A button that cycles through playback speed rates

## Import

```ts
import '@videojs/html/ui/playback-rate-button';
```

## Anatomy

```html
<media-playback-rate-button></media-playback-rate-button>
```

## 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 `commandfor` is set, activation opens the linked playback-rate menu instead of cycling through rates. Use this mode when the button is the trigger for a `<media-menu>` that contains playback-rate options.

## Styling

Display the current rate using the `data-rate` attribute:

```css
media-playback-rate-button::after {
  content: attr(data-rate) "\00D7";
}
```

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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-playback-rate-button class="media-playback-rate-button"> </media-playback-rate-button>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}

.media-playback-rate-button::after {
  content: attr(data-rate) "\00D7";
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/playback-rate-button';
```

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

### State

State is reflected as data attributes for CSS styling.

| 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/html/reference/components/live-button -->

# media-live-button

Accessible live indicator button that seeks to the live edge when pressed

## Import

```ts
import '@videojs/html/ui/live-button';
```

## Anatomy

```html
<media-live-button></media-live-button>
```

## 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/html/reference/api/feature-live) for `liveEdgeStart` and `targetLiveWindow`, [time](https://videojs.org/docs/framework/html/reference/api/feature-time) for `currentTime` and the `seek()` action, and [buffer](https://videojs.org/docs/framework/html/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/html/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:

```css
media-live-button { color: gray; }
media-live-button[data-live-edge] { color: red; }
media-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.

**index.html**

```html
<live-video-player class="html-live-button-basic">
  <media-container>
    <hlsjs-video src="https://stream.mux.com/v69RSHhFelSm4701snP22dYz2jICy4E4FUyk02rW4gxRM.m3u8" autoplay muted playsinline></hlsjs-video>
    <div class="html-live-button-basic__buttons">
      <media-seek-button seconds="-30" class="html-live-button-basic__seek">&#9194; 30s</media-seek-button>
      <media-live-button class="html-live-button-basic__live">
        <span class="html-live-button-basic__dot"></span>
        Live
      </media-live-button>
    </div>
  </media-container>
</live-video-player>
```

**index.css**

```css
.html-live-button-basic media-container {
  position: relative;
}

.html-live-button-basic media-container hlsjs-video {
  display: block;
  width: 100%;
}

.html-live-button-basic__buttons {
  position: absolute;
  bottom: 10px;
  left: 10px;
  display: flex;
  gap: 8px;
}

.html-live-button-basic__seek,
.html-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);
}

.html-live-button-basic__live[data-live-edge] {
  cursor: default;
}

.html-live-button-basic__dot {
  width: 8px;
  height: 8px;
  background: gray;
  border-radius: 50%;
}

.html-live-button-basic__live[data-live-edge] .html-live-button-basic__dot {
  background: red;
}
```

**index.ts**

```ts
import '@videojs/html/live-video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/live-button';
import '@videojs/html/ui/seek-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/airplay-button -->

# media-airplay-button

Accessible AirPlay toggle button that opens the WebKit playback target picker and reflects session state

## Import

```ts
import '@videojs/html/ui/airplay-button';
```

## Anatomy

```html
<media-airplay-button></media-airplay-button>
```

## 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 element receives the native `hidden` attribute.

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/html/reference/api/feature-remote-playback) store feature alongside `<media-cast-button>`: 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:

```css
/* AirPlay active */
media-airplay-button[data-airplay-state="connected"] {
  color: var(--accent);
}
```

Use `data-disabled` to style an explicitly disabled, available button:

```css
media-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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-airplay-button class="media-airplay-button">
      <span class="connected">Stop AirPlay</span>
      <span class="not-connected">Start AirPlay</span>
    </media-airplay-button>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.media-airplay-button .connected,
.media-airplay-button .not-connected {
  display: none;
}

/* Connected: AirPlay active */
.media-airplay-button[data-airplay-state="connected"] .connected {
  display: inline;
}

/* Not connected: ready to AirPlay */
.media-airplay-button:not([data-airplay-state="connected"]) .not-connected {
  display: inline;
}

/* Explicitly disabled while AirPlay is available. */
.media-airplay-button[data-disabled] {
  cursor: not-allowed;
  opacity: 0.5;
  filter: grayscale(1);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/airplay-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/cast-button -->

# media-cast-button

Accessible Cast toggle button with state reflection and keyboard support

## Import

```ts
import '@videojs/html/ui/cast-button';
```

## Anatomy

```html
<media-cast-button></media-cast-button>
```

## 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 element receives the native `hidden` attribute.
- **`"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/html/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/html/guides/casting) for the complete setup.

## Styling

Style based on cast and disabled state:

```css
/* During an active session */
media-cast-button[data-cast-state="connected"] {
  color: blue;
}

/* Cast is supported, but no device is reachable */
media-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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <hlsjs-video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM.m3u8" autoplay muted playsinline loop></hlsjs-video>
    <google-cast></google-cast>
    <media-cast-button class="media-cast-button">
      <span class="connected">Stop casting</span>
      <span class="disconnected">Start casting</span>
    </media-cast-button>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.media-cast-button .connected {
  display: none;
}
.media-cast-button .disconnected {
  display: none;
}
.media-cast-button[data-cast-state="connected"] .connected {
  display: inline;
}
.media-cast-button:not([data-cast-state="connected"]) .disconnected {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/extensions/google-cast';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/cast-button';
```

## 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 reflected as data attributes for CSS styling.

| 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/html/reference/components/slider -->

# media-slider

A composable slider component with track, fill, thumb, preview, and value parts

## Import

```ts
import '@videojs/html/ui/slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/slider-thumbnail';
import '@videojs/html/ui/slider-value';
```

## Anatomy

```html
<media-slider>
  <media-slider-track>
    <media-slider-fill></media-slider-fill>
  </media-slider-track>
  <media-slider-thumb></media-slider-thumb>
  <media-slider-preview>
    <media-slider-thumbnail>
      <img alt="" decoding="async" />
    </media-slider-thumbnail>
    <media-slider-value type="pointer"></media-slider-value>
  </media-slider-preview>
</media-slider>
```

## 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/html/reference/components/time-slider) and [volume slider](https://videojs.org/docs/framework/html/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.

`media-slider-thumbnail` supplies the pointer value and draws the image in its shadow DOM. Supply an `<img>` child to replace it: the element controls `src` and `srcset` on your image, and 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/html/reference/components/slider#root-css-custom-properties) to position fill, thumb, and preview elements:

```css
media-slider-fill {
  width: var(--media-slider-fill);
}

media-slider-thumb {
  left: var(--media-slider-fill);
}
```

Style based on [interaction state](https://videojs.org/docs/framework/html/reference/components/slider#root-data-attributes):

```css
media-slider[data-interactive] media-slider-track {
  height: 6px;
}
media-slider[data-pointing] media-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.

**index.html**

```html
<div class="demo">
  <media-slider class="media-slider" value="50">
    <media-slider-track class="media-slider-track">
      <media-slider-fill class="media-slider-fill"></media-slider-fill>
    </media-slider-track>
    <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
  </media-slider>
</div>
```

**index.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);
}
```

**index.ts**

```ts
import '@videojs/html/ui/slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
```

### With Preview

A slider with a pointer-tracking preview that displays the value at the current pointer position.

**index.html**

```html
<div class="demo">
  <media-slider class="media-slider" value="50">
    <media-slider-track class="media-slider-track">
      <media-slider-fill class="media-slider-fill"></media-slider-fill>
    </media-slider-track>
    <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
    <media-slider-preview class="preview">
      <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
    </media-slider-preview>
  </media-slider>
</div>
```

**index.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;
}
```

**index.ts**

```ts
import '@videojs/html/ui/slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/slider-value';
```

## API Reference

### media-slider

#### 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` (attribute `large-step`) | `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` (attribute `thumb-alignment`) | `'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 reflected as data attributes for CSS styling.

| 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). |

#### Events

| Event | Description |
| --- | --- |
| `drag-end` | Fired when a pointer drag ends. |
| `drag-start` | Fired when a pointer drag starts. |
| `value-change` | Fired while the slider value changes during an interaction. |
| `value-commit` | Fired when an interaction commits the slider value. |

### media-slider-buffer

Displays the buffered range on the slider track.

### media-slider-fill

Displays the filled portion from start to the current value.

### media-slider-preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |

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

### media-slider-thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

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

### media-slider-track

Contains the slider's visual track and interactive hit zone.

### media-slider-value

Writes the formatted current or pointer slider value into its own text content, replacing any children.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

### media-slider-thumbnail

`<media-thumbnail>` whose `time` follows the slider pointer. Left empty, it draws an image of its own; supply an `<img>` child to compose overlays or loading indicators beside the image it controls.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/time-slider -->

# media-time-slider

A slider component for seeking through media playback time

## Import

```ts
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-buffer';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/slider-thumbnail';
import '@videojs/html/ui/slider-value';
import '@videojs/html/ui/time-slider-chapters';
import '@videojs/html/ui/time-slider-chapter-title';
```

## Anatomy

```html
<media-time-slider>
  <media-slider-track>
    <media-slider-buffer></media-slider-buffer>
    <media-slider-fill></media-slider-fill>
  </media-slider-track>
  <media-slider-thumb></media-slider-thumb>
  <media-slider-preview>
    <media-time-slider-chapter-title></media-time-slider-chapter-title>
    <media-slider-value type="pointer"></media-slider-value>
  </media-slider-preview>
</media-time-slider>
```

Add `<media-time-slider-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.

```html
<media-time-slider-chapters>
  <template>
    <div>
      <media-slider-track>
        <media-slider-buffer></media-slider-buffer>
        <media-slider-fill></media-slider-fill>
      </media-slider-track>
    </div>
  </template>
</media-time-slider-chapters>
```

The required template must contain exactly one HTML root element. It remains in the light DOM and is cloned for each normalized chapter range. When no chapter cues are available, it is cloned once as a full-width, cue-less range.

## 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/html/reference/components/time-slider#root-css-custom-properties) to style the fill, pointer, and buffer levels:

```css
media-time-slider::before {
  width: var(--media-slider-fill);
}
```

Use `data-seeking` to style during active seek operations:

```css
media-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

`<media-time-slider-chapter-title>` 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.

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time-slider class="media-time-slider">
      <media-slider-track class="media-slider-track">
        <media-slider-buffer class="media-slider-buffer"></media-slider-buffer>
        <media-slider-fill class="media-slider-fill"></media-slider-fill>
      </media-slider-track>
      <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
      <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
    </media-time-slider>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-buffer';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-value';
```

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

**index.html**

```html
<video-player class="video-player">
  <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>
    <media-time-slider class="media-time-slider">
      <media-time-slider-chapters class="media-slider-chapters">
        <template>
          <div class="media-slider-chapter">
            <media-slider-track class="media-slider-track">
              <media-slider-buffer class="media-slider-buffer"></media-slider-buffer>
              <media-slider-fill class="media-slider-fill"></media-slider-fill>
            </media-slider-track>
          </div>
        </template>
      </media-time-slider-chapters>
      <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
      <media-slider-preview class="media-slider-preview">
        <media-time-slider-chapter-title class="media-slider-chapter-title"></media-time-slider-chapter-title>
        <media-slider-value type="pointer"></media-slider-value>
      </media-slider-preview>
    </media-time-slider>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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;
  display: block;
  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;
  display: block;
  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;
  display: block;
  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);
  display: block;
  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;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/time-slider-chapters';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-buffer';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/time-slider-chapter-title';
import '@videojs/html/ui/slider-value';
```

## API Reference

### media-time-slider

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `changeThrottle` (attribute `change-throttle`) | `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` (attribute `large-step`) | `number` | — | Large step increment (Page Up/Down keys). |
| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
| `pauseOnDrag` (attribute `pause-on-drag`) | `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` (attribute `thumb-alignment`) | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |

#### State

State is reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `drag-end` | Fired when a pointer drag ends. |
| `drag-start` | Fired when a pointer drag starts. |

### media-time-slider-chapter-title

Displays the chapter title at the current pointer or keyboard position.

### media-time-slider-chapters

Clones a light-DOM template once per normalized chapter range.

The required template must contain exactly one HTML root element. When no chapter cues are available, the template is cloned once for a full-duration range.

### media-slider-buffer

Displays the buffered range on the slider track.

### media-slider-fill

Displays the filled portion from start to the current value.

### media-slider-preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |

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

### media-slider-thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

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

### media-slider-track

Contains the slider's visual track and interactive hit zone.

### media-slider-value

Writes the formatted current or pointer slider value into its own text content, replacing any children.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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/html/reference/components/volume-slider -->

# media-volume-slider

A slider component for controlling media playback volume

## Import

```ts
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-preview';
import '@videojs/html/ui/slider-value';
```

## Anatomy

```html
<media-volume-slider>
  <media-slider-track>
    <media-slider-fill></media-slider-fill>
  </media-slider-track>
  <media-slider-thumb></media-slider-thumb>
  <media-slider-preview>
    <media-slider-value type="pointer"></media-slider-value>
  </media-slider-preview>
</media-volume-slider>
```

## 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 element receives native `hidden`, `data-hidden`, and disabled ARIA semantics. This is independent of `mutedAvailability`, which controls whether the mute button is shown.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/html/reference/components/volume-slider#root-css-custom-properties) to style the fill and pointer levels:

```css
media-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.

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-mute-button class="media-mute-button">
      <span class="muted">Unmute</span>
      <span class="unmuted">Mute</span>
    </media-mute-button>
    <media-volume-slider class="media-volume-slider">
      <media-slider-track class="media-slider-track">
        <media-slider-fill class="media-slider-fill"></media-slider-fill>
      </media-slider-track>
      <media-slider-thumb class="media-slider-thumb"></media-slider-thumb>
      <media-slider-value type="pointer" class="media-slider-value"></media-slider-value>
    </media-volume-slider>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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-mute-button .muted {
  display: none;
}
.media-mute-button .unmuted {
  display: none;
}
.media-mute-button[data-muted] .muted {
  display: inline;
}
.media-mute-button:not([data-muted]) .unmuted {
  display: inline;
}

.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;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/slider-value';
```

## API Reference

### media-volume-slider

#### 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` (attribute `large-step`) | `number` | — | Large step increment (Page Up/Down keys). |
| `orientation` | `'horizontal' \| 'vertical'` | — | Axis of slider movement. |
| `step` | `number` | `DEFAULT_VOLUME_STEP` | Step increment for value changes (arrow keys). |
| `thumbAlignment` (attribute `thumb-alignment`) | `'center' \| 'edge'` | — | How the thumb aligns at the track edges. `edge` constrains the thumb within track bounds. |
| `wheelStep` (attribute `wheel-step`) | `number` | `DEFAULT_VOLUME_STEP` | Step increment for wheel scrolling. |

#### State

State is reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `drag-end` | Fired when a pointer drag ends. |
| `drag-start` | Fired when a pointer drag starts. |

### media-slider-fill

Displays the filled portion from start to the current value.

### media-slider-preview

Positioning container for preview content that tracks the pointer along the slider.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `overflow` | `'clamp' \| 'visible'` | — | How the preview handles slider boundaries. `clamp` keeps it within bounds; `visible` lets it extend past them. |

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

### media-slider-thumb

Draggable handle for setting the slider value. Receives focus and handles keyboard interaction.

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

### media-slider-track

Contains the slider's visual track and interactive hit zone.

### media-slider-value

Writes the formatted current or pointer slider value into its own text content, replacing any children.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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/html/reference/components/menu -->

# media-menu

A composable menu component for settings, option selection, and actions

## Import

```ts
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-item';
import '@videojs/html/ui/menu-group';
import '@videojs/html/ui/menu-group-label';
import '@videojs/html/ui/menu-separator';
import '@videojs/html/ui/menu-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-checkbox-item';
import '@videojs/html/ui/menu-item-indicator';
```

## Anatomy

`<media-menu>` is the root menu and its one positioned popup. The root and nested `<media-menu-content>` elements are its direct children and share that popup.

```html
<button type="button" commandfor="settings-menu">Settings</button>

<media-menu id="settings-menu">
  <media-menu-content>
    <!-- Parent menu item that opens a submenu -->
    <media-menu-item commandfor="submenu">
      Open submenu
    </media-menu-item>

    <!-- Other parent menu items -->
    <media-menu-group>
      <media-menu-group-label></media-menu-group-label>
      <media-menu-checkbox-item>
        <media-menu-item-indicator></media-menu-item-indicator>
      </media-menu-checkbox-item>
    </media-menu-group>
    <media-menu-separator></media-menu-separator>
    <media-menu-item></media-menu-item>
  </media-menu-content>

  <!-- Sibling Content opened by the parent item -->
  <media-menu-content id="submenu">
    <media-menu-item>Back</media-menu-item>
    <media-menu-radio-group>
      <media-menu-group-label></media-menu-group-label>
      <media-menu-radio-item>
        <media-menu-item-indicator></media-menu-item-indicator>
      </media-menu-radio-item>
    </media-menu-radio-group>
  </media-menu-content>
</media-menu>
```

## 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/html/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.

To create a submenu, add another `<media-menu-content>` as a sibling, give it an `id`, and point the parent `<media-menu-item>` at it with `commandfor`.

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/html/reference/components/playback-rate-radio-group), [QualityRadioGroup](https://videojs.org/docs/framework/html/reference/components/quality-radio-group), [AudioTrackRadioGroup](https://videojs.org/docs/framework/html/reference/components/audio-track-radio-group), and [CaptionsRadioGroup](https://videojs.org/docs/framework/html/reference/components/captions-radio-group).

The generated radio group publishes its state to the `<media-menu>` that contains it. Add an element with `data-part="hint"` inside the parent `<media-menu-item>` and the menu writes the selected label into it:

```html
<media-menu-item commandfor="quality-menu">
  Quality
  <span data-part="hint"></span>
</media-menu-item>
```

## 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 `<media-menu>` receives `data-open`, `data-side`, and `data-align`. Each `<media-menu-content>` receives menu state such as `data-open` and `data-submenu`; a content element 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
media-menu[data-open] {
  opacity: 1;
}

media-menu-content[data-child-open] {
  translate: -100% 0;
}

media-menu-item[data-highlighted] {
  background: rgba(255, 255, 255, 0.16);
  transition: background-color 100ms ease-in-out;
}

media-menu-item[data-highlighted=""] {
  transition-duration: 0ms;
}

media-menu-radio-item[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 `<media-menu-group-label>` inside grouped choices so the group receives an accessible label.

## Examples

### Basic usage

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <hlsjs-video
      class="video-media"
      src="https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8"
      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" />
    </hlsjs-video>
    <div class="menu-bar">
      <button type="button" commandfor="settings-menu" class="settings-trigger">Settings</button>
      <media-menu id="settings-menu" side="top" align="end" class="menu">
        <media-menu-content class="menu-content">
          <media-menu-item commandfor="quality-menu" class="menu-item">
            <span>Quality</span>
            <span class="menu-value">
              <span data-part="hint"></span>
              <span aria-hidden="true">›</span>
            </span>
          </media-menu-item>
          <media-menu-item commandfor="audio-menu" class="menu-item">
            <span>Audio</span>
            <span class="menu-value">
              <span data-part="hint"></span>
              <span aria-hidden="true">›</span>
            </span>
          </media-menu-item>
          <media-menu-item commandfor="speed-menu" class="menu-item">
            <span>Speed</span>
            <span class="menu-value">
              <span data-part="hint"></span>
              <span aria-hidden="true">›</span>
            </span>
          </media-menu-item>
          <media-menu-item commandfor="captions-menu" class="menu-item">
            <span>Captions</span>
            <span class="menu-value">
              <span data-part="hint"></span>
              <span aria-hidden="true">›</span>
            </span>
          </media-menu-item>
          <media-menu-item class="menu-item">Copy link</media-menu-item>
        </media-menu-content>
        <media-menu-content id="quality-menu" class="menu-panel">
          <media-menu-item class="menu-back">
            <span aria-hidden="true">‹</span>
            Quality
          </media-menu-item>
          <media-quality-radio-group class="menu-group">
            <template>
              <media-menu-radio-item class="menu-item">
                <span>
                  <span data-part="label"></span>
                  <sup data-part="tier" class="menu-tier"></sup>
                </span>
                <span data-part="badge" class="menu-badge"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-quality-radio-group>
        </media-menu-content>
        <media-menu-content id="audio-menu" class="menu-panel">
          <media-menu-item class="menu-back">
            <span aria-hidden="true">‹</span>
            Audio
          </media-menu-item>
          <media-audio-track-radio-group class="menu-group">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-audio-track-radio-group>
        </media-menu-content>
        <media-menu-content id="speed-menu" class="menu-panel">
          <media-menu-item class="menu-back">
            <span aria-hidden="true">‹</span>
            Speed
          </media-menu-item>
          <media-playback-rate-radio-group class="menu-group">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-playback-rate-radio-group>
        </media-menu-content>
        <media-menu-content id="captions-menu" class="menu-panel">
          <media-menu-item class="menu-back">
            <span aria-hidden="true">‹</span>
            Captions
          </media-menu-item>
          <media-captions-radio-group class="menu-group">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-captions-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-media {
  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;
  overflow: hidden;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  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-item[data-availability="unavailable"] {
  display: none;
}

.menu-value {
  display: inline-flex;
  gap: 8px;
  align-items: center;
  color: rgba(255, 255, 255, 0.72);
}

.menu-value [aria-hidden] {
  font-size: 18px;
  line-height: 1;
}

.menu-back [aria-hidden] {
  font-size: 18px;
  line-height: 1;
  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-indicator {
  opacity: 0;
}

media-menu-radio-item[aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-item';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/quality-radio-group';
import '@videojs/html/ui/audio-track-radio-group';
import '@videojs/html/ui/playback-rate-radio-group';
import '@videojs/html/ui/captions-radio-group';
```

## API Reference

### media-menu

Root menu state and positioned popup. Content pages are direct children.

#### 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` (attribute `close-on-escape`) | `boolean` | `true` | Close the menu when Escape is pressed at root level. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the menu when clicking outside. Root menus only. |
| `defaultOpen` (attribute `default-open`) | `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 reflected as data attributes for CSS styling.

| 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). |

#### Events

| Event | Description |
| --- | --- |
| `open-change` | Fired before the menu's open state changes. Cancel the event to prevent the change. |

### media-menu-checkbox-item

Menu item that toggles `checked` when activated and leaves the menu open. The element itself takes `role="menuitemcheckbox"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the item is currently checked. |
| `disabled` | `boolean` | — | Whether the item is disabled. |

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

#### Events

| Event | Description |
| --- | --- |
| `checked-change` | Fired when the checked state changes. |

### media-menu-content

One accessible menu page. Root and nested pages are sibling children of `<media-menu>`.

#### Events

| Event | Description |
| --- | --- |
| `open-change` | |

### media-menu-group

Groups related menu items; the element itself takes `role="group"`. A `<media-menu-group-label>` child names the group unless it already has an `aria-label` or `aria-labelledby`.

### media-menu-group-label

Non-interactive label that names its enclosing `<media-menu-group>` or `<media-menu-radio-group>`.

### media-menu-item

Menu action; the element itself takes `role="menuitem"`. Activation fires a cancelable `select` event and then closes the menu, unless `commandfor` names a nested `<media-menu-content>` page to open instead.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Whether the item is disabled. |

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

### media-menu-item-indicator

Decorative checked-state mark inside a menu item, hidden from assistive technology. It stays `hidden` unless `checked` or `force-mount` is set; option radio groups set `checked` on the indicators in the items they generate.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Whether the indicator is currently shown. Typically bound to the parent item's checked state. |
| `forceMount` (attribute `force-mount`) | `boolean` | — | When `true`, renders even when unchecked (useful for animating out). Defaults to `false`. |

### media-menu-radio-group

Group of mutually exclusive `<media-menu-radio-item>` children; the element itself takes `role="group"`.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | The currently selected value. |

#### Events

| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |

### media-menu-radio-item

Menu item that selects its `value` in the enclosing `<media-menu-radio-group>` and closes the menu. The element itself takes `role="menuitemradio"`, checked while its value matches the group's.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | — | Whether the item is disabled. |
| `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. |

### media-menu-separator

Visual divider between groups of menu items; the element itself takes `role="separator"`.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/popover -->

# media-popover

A popover component for displaying contextual content anchored to a trigger

## Import

```ts
import '@videojs/html/ui/popover';
```

## Anatomy

```html
<button type="button" commandfor="my-popover">Open</button>
<media-popover id="my-popover">Content</media-popover>
```

## 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/html/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.

`<media-popover>` is the popup. A trigger links to it through `commandfor` set to the popup’s `id`. If the popup has no `id`, it uses the element immediately before it as the trigger. It gives the popup a generated `id` and sets the trigger’s `commandfor` to that value. That element must not already target another popup through `commandfor`.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/html/reference/components/popover#root-css-custom-properties) for positioning offsets:

```css
media-popover {
  --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
media-popover[data-open] {
  display: block;
}
media-popover[data-starting-style] {
  opacity: 0;
}
media-popover[data-ending-style] {
  opacity: 0;
}
media-popover[data-side="top"] {
  transform-origin: bottom center;
}
media-popover[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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="bar">
      <button type="button" commandfor="popover-demo" class="trigger">Settings</button>
      <media-popover id="popover-demo" class="media-popover">
        <div class="popup">Popover content</div>
      </media-popover>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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);
}

.media-popover {
  padding: 12px 16px;
  font-size: 14px;
  color: white;
  white-space: nowrap;
  background: rgba(0, 0, 0, 0.85);
  border-radius: 8px;
  backdrop-filter: blur(10px);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/popover';
```

## API Reference

### media-popover

#### 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` (attribute `close-delay`) | `number` | `0` | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | `true` | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` (attribute `default-open`) | `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` (attribute `open-on-hover`) | `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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `open-change` | Fired when the popover's open state changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/volume-popover -->

# media-volume-popover

A volume-aware popover that keeps mute available when volume level controls are unavailable

## Import

```ts
import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
```

## Anatomy

```html
<media-mute-button commandfor="volume-popup"></media-mute-button>
<media-volume-popover id="volume-popup">
  <media-volume-slider></media-volume-slider>
</media-volume-popover>
```

## Behavior

`<media-volume-popover>` combines [popover behavior](https://videojs.org/docs/framework/html/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.

The trigger can target the popup with `commandfor`. An immediately adjacent trigger is linked automatically when neither element has an authored ID.

## Styling

The popup reflects `data-availability="available"` while it can render volume controls.

When it cannot, the element also receives native `hidden` and `data-hidden`.

```css
media-volume-popover[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

**index.html**

```html
<video-player class="html-volume-popover-basic">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="html-volume-popover-basic__controls">
      <media-mute-button commandfor="volume-popover-demo" class="html-volume-popover-basic__trigger">
        <span class="muted">Unmute</span>
        <span class="unmuted">Mute</span>
      </media-mute-button>
      <media-volume-popover id="volume-popover-demo" open-on-hover side="top" class="html-volume-popover-basic__popup">
        <media-volume-slider orientation="vertical" class="html-volume-popover-basic__slider">
          <media-slider-track class="html-volume-popover-basic__track">
            <media-slider-fill class="html-volume-popover-basic__fill"></media-slider-fill>
          </media-slider-track>
          <media-slider-thumb class="html-volume-popover-basic__thumb"></media-slider-thumb>
        </media-volume-slider>
      </media-volume-popover>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.html-volume-popover-basic media-container {
  position: relative;
  display: block;
}

.html-volume-popover-basic video {
  width: 100%;
}

.html-volume-popover-basic__controls {
  position: absolute;
  bottom: 10px;
  left: 10px;
}

.html-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);
}

.html-volume-popover-basic__trigger .muted,
.html-volume-popover-basic__trigger .unmuted {
  display: none;
}

.html-volume-popover-basic__trigger[data-muted] .muted,
.html-volume-popover-basic__trigger:not([data-muted]) .unmuted {
  display: inline;
}

.html-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;
}

.html-volume-popover-basic__slider {
  position: relative;
  display: block;
  width: 16px;
  height: 96px;
  margin: auto;
  cursor: pointer;
}

.html-volume-popover-basic__track {
  position: absolute;
  top: 0;
  bottom: 0;
  left: 6px;
  width: 4px;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.html-volume-popover-basic__fill {
  position: absolute;
  right: 0;
  bottom: 0;
  left: 0;
  height: var(--media-slider-fill);
  background: white;
  border-radius: inherit;
}

.html-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%);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/volume-popover';
import '@videojs/html/ui/volume-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
```

## API Reference

### media-volume-popover

A volume-aware popover that keeps its adjacent mute trigger available as a fallback.

#### 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` (attribute `close-delay`) | `number` | — | Delay in ms before closing after pointer leaves. |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | — | Close the popup when the Escape key is pressed. |
| `closeOnOutsideClick` (attribute `close-on-outside-click`) | `boolean` | — | Close the popup when clicking outside the trigger and popup. |
| `defaultOpen` (attribute `default-open`) | `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` (attribute `open-on-hover`) | `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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `open-change` | Fired when the popover's open state changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/audio-track-radio-group -->

# media-audio-track-radio-group

A menu radio group for selecting an audio track

Creates radio items from the player audio track state and selects the enabled track.

## Import

```ts
import '@videojs/html/ui/audio-track-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```

## Anatomy

```html
<media-audio-track-radio-group>
  <template>
    <media-menu-radio-item>
      <span data-part="label"></span>
      <media-menu-item-indicator></media-menu-item-indicator>
    </media-menu-radio-item>
  </template>
</media-audio-track-radio-group>
```

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

`<media-audio-track-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.

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

The element receives an accessible label from the `label` property or defaults to `Audio`.

## Examples

### Basic usage

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <hlsjs-video
      class="video-media"
      src="https://stream.mux.com/s41JYeqIpBMBzE4OzxDyGR2yrp2hD1CQ6gJN9SlVGDQ.m3u8"
      autoplay
      crossorigin="anonymous"
      muted
      playsinline
      loop
    ></hlsjs-video>
    <div class="menu-bar">
      <button type="button" commandfor="audio-menu" class="settings-trigger">Audio</button>
      <media-menu id="audio-menu" side="top" align="end" class="menu">
        <media-menu-content>
          <media-audio-track-radio-group class="menu-group" label="Audio tracks">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-audio-track-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-media {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.menu-bar:has([data-availability="unavailable"]) {
  display: none;
}

.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;
  box-sizing: border-box;
  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;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  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;
}

media-menu-radio-item[aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/audio-track-radio-group';
```

## API Reference

### media-audio-track-radio-group

Menu radio group that generates a `<media-menu-radio-item>` per available audio track and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether audio track selection is disabled. |
| `formatTrack` (attribute `format-track`) | `((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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/captions-radio-group -->

# media-captions-radio-group

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

```ts
import '@videojs/html/ui/captions-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```

## Anatomy

```html
<media-captions-radio-group>
  <template>
    <media-menu-radio-item>
      <span data-part="label"></span>
      <media-menu-item-indicator></media-menu-item-indicator>
    </media-menu-radio-item>
  </template>
</media-captions-radio-group>
```

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

`<media-captions-radio-group>` generates `<media-menu-radio-item>` children, including the `Off` item. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.

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

The element receives an accessible label from the `label` property or defaults to `Captions`.

## Examples

### Basic usage

**index.html**

```html
<video-player class="video-player">
  <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 class="menu-bar">
      <button type="button" commandfor="captions-menu" class="settings-trigger">Captions</button>
      <media-menu id="captions-menu" side="top" align="end" class="menu">
        <media-menu-content>
          <media-captions-radio-group class="menu-group" label="Captions">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-captions-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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;
  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;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  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;
}

media-menu-radio-item[aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/captions-radio-group';
```

## API Reference

### media-captions-radio-group

Menu radio group that generates an Off `<media-menu-radio-item>` plus one per captions and subtitles track, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether track selection is disabled. |
| `formatTrack` (attribute `format-track`) | `((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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/playback-rate-radio-group -->

# media-playback-rate-radio-group

A menu radio group for selecting playback speed

Creates radio items from the player playback rate state and selects the playback speed.

## Import

```ts
import '@videojs/html/ui/playback-rate-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```

## Anatomy

```html
<media-playback-rate-radio-group>
  <template>
    <media-menu-radio-item>
      <span data-part="label"></span>
      <media-menu-item-indicator></media-menu-item-indicator>
    </media-menu-radio-item>
  </template>
</media-playback-rate-radio-group>
```

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

`<media-playback-rate-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.

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

The element receives an accessible label from the `label` property or defaults to `Playback rate`. Override it with `aria-label` or `aria-labelledby`.

## Examples

### Basic usage

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <div class="menu-bar">
      <button type="button" commandfor="speed-menu" class="settings-trigger">Speed</button>
      <media-menu id="speed-menu" side="top" align="end" class="menu">
        <media-menu-content>
          <media-playback-rate-radio-group class="menu-group" aria-label="Speed">
            <template>
              <media-menu-radio-item class="menu-item">
                <span data-part="label"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-playback-rate-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-player 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;
  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;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  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;
}

media-menu-radio-item[aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/playback-rate-radio-group';
```

## API Reference

### media-playback-rate-radio-group

Menu radio group that generates a `<media-menu-radio-item>` per available playback rate and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether playback rate selection is disabled. |
| `formatRate` (attribute `format-rate`) | `((rate: number) => string)` | `formatPlaybackRate` | Custom formatter for visible playback rate labels. |

#### State

State is reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/quality-radio-group -->

# media-quality-radio-group

A menu radio group for selecting video quality

Creates radio items from the player video rendition state and selects automatic or manual quality.

## Import

```ts
import '@videojs/html/ui/quality-radio-group';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
```

## Anatomy

```html
<media-quality-radio-group>
  <template>
    <media-menu-radio-item>
      <span data-part="label"></span>
      <span data-part="tier"></span>
      <span data-part="badge"></span>
      <media-menu-item-indicator></media-menu-item-indicator>
    </media-menu-radio-item>
  </template>
</media-quality-radio-group>
```

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

`<media-quality-radio-group>` generates `<media-menu-radio-item>` children. Add an optional `<template>` with a single `<media-menu-radio-item>` to customize each generated item.

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

The element receives an accessible label from the `label` property or defaults to `Quality`.

## Examples

### Basic usage

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <hlsjs-video
      class="video-media"
      src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4.m3u8"
      autoplay
      crossorigin="anonymous"
      muted
      playsinline
      loop
    ></hlsjs-video>
    <div class="menu-bar">
      <button type="button" commandfor="quality-menu" class="settings-trigger">Quality</button>
      <media-menu id="quality-menu" side="top" align="end" class="menu">
        <media-menu-content>
          <media-quality-radio-group class="menu-group" label="Quality">
            <template>
              <media-menu-radio-item class="menu-item">
                <span>
                  <span data-part="label"></span>
                  <sup data-part="tier" class="menu-tier"></sup>
                </span>
                <span data-part="badge" class="menu-badge"></span>
                <media-menu-item-indicator force-mount class="menu-indicator">✓</media-menu-item-indicator>
              </media-menu-radio-item>
            </template>
          </media-quality-radio-group>
        </media-menu-content>
      </media-menu>
    </div>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

.video-media {
  width: 100%;
}

.menu-bar {
  position: absolute;
  right: 10px;
  bottom: 10px;
}

.menu-bar:has([data-availability="unavailable"]) {
  display: none;
}

.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;
  box-sizing: border-box;
  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;
  overflow: auto;
  overscroll-behavior: none;
  font-size: 14px;
  color: white;
  background: rgba(0, 0, 0, 0.88);
  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;
}

media-menu-radio-item[aria-checked="true"] .menu-indicator {
  opacity: 1;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/media/hlsjs-video';
import '@videojs/html/ui/menu';
import '@videojs/html/ui/menu-content';
import '@videojs/html/ui/menu-radio-item';
import '@videojs/html/ui/menu-item-indicator';
import '@videojs/html/ui/quality-radio-group';
```

## API Reference

### media-quality-radio-group

Menu radio group that generates an Auto `<media-menu-radio-item>` plus one per video rendition, and shares the selected label and availability with an enclosing menu. An optional `<template>` holding one `<media-menu-radio-item>` customizes each generated item; its `data-part` `label`, `tier`, and `badge` descendants receive the rendition's text.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `disabled` | `boolean` | `false` | Whether quality selection is disabled. |
| `formatRendition` (attribute `format-rendition`) | `((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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `value-change` | Fired when the selected value changes. |

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/time -->

# media-time

Time display components for showing current time, duration, and remaining time in a video player

## Import

```ts
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```

## Anatomy

```html
<media-time-group>
  <media-time type="current"></media-time>
  <media-time-separator></media-time-separator>
  <media-time type="duration"></media-time>
</media-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.

```html
<media-time toggle></media-time>
<media-time toggle type="remaining"></media-time>
<media-time toggle type="duration"></media-time>
```

## 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 `<media-time>` has:

- `role="time"` and `datetime` 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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time class="media-time" type="current"></media-time>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```

### Current / Duration

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time-group class="time-group">
      <media-time type="current"></media-time>
      <media-time-separator></media-time-separator>
      <media-time type="duration"></media-time>
    </media-time-group>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```

### Remaining

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time class="media-time" type="remaining"></media-time>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```

### Custom Separator

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time-group class="time-group">
      <media-time type="current"></media-time>
      <media-time-separator> of </media-time-separator>
      <media-time type="duration"></media-time>
    </media-time-group>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
import '@videojs/html/ui/time-group';
import '@videojs/html/ui/time-separator';
```

### Custom Negative Sign

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-time class="media-time" type="remaining" negative-sign="~"></media-time>
  </media-container>
</video-player>
```

**index.css**

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

.video-player 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);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/time';
```

## API Reference

### media-time

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` (attribute `negative-sign`) | `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 reflected as data attributes for CSS styling.

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

### media-time-group

Container for composed `<media-time>` and `<media-time-separator>` displays.

### media-time-separator

Divider between time values. Hidden from screen readers.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/title -->

# media-title

Displays the resolved content title for the current media

## Import

```ts
import '@videojs/html/ui/title';
```

## Anatomy

```html
<media-title></media-title>
```

## Behavior

The element renders the resolved title directly as text and owns that text: it replaces any authored content whenever the title updates. Set the title on the player instead.

```html
<video-player content-title="Big Buck Bunny">
  <video src="video.mp4"></video>
  <media-title></media-title>
</video-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/html/reference/api/feature-metadata), which the video and audio presets include.

`title` already means the tooltip on an element, so the player takes the title as `content-title`, reflected by the `contentTitle` property:

```ts
const player = document.querySelector("video-player");

player.contentTitle = "Sintel";
```

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

When no title resolves, the element sets the native `hidden` attribute and `data-hidden`, so it takes up no space and a background or gradient never sits over empty space.

To fade the title in and out with the controls, use the root’s `data-visible` attribute:

```css
media-title {
  opacity: 0;
  transition: opacity 150ms ease-out;
}

media-title[data-visible] {
  opacity: 1;
}
```

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

**index.html**

```html
<video-player content-title="Big Buck Bunny">
  <media-container class="html-title-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline loop></video>
    <media-title class="html-title-basic__title"></media-title>
    <media-play-button class="html-title-basic__button">
      <span class="show-when-paused">Play</span>
      <span class="show-when-playing">Pause</span>
    </media-play-button>
  </media-container>
</video-player>
```

**index.css**

```css
.html-title-basic {
  position: relative;
  display: block;
}

.html-title-basic video {
  display: block;
  width: 100%;
}

/* The element sets native `hidden` until a title resolves, so the gradient
   never sits over empty space without this demo doing anything. */
.html-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);
}

.html-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);
}

.html-title-basic__button .show-when-paused {
  display: none;
}

.html-title-basic__button .show-when-playing {
  display: none;
}

.html-title-basic__button[data-paused] .show-when-paused {
  display: inline;
}

.html-title-basic__button:not([data-paused]) .show-when-playing {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/title';
```

## API Reference

### State

State is reflected as data attributes for CSS styling.

| 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/html/reference/components/poster -->

# media-poster

Poster image component that displays a thumbnail until video playback starts

## Import

```ts
import '@videojs/html/ui/poster';
```

## Anatomy

```html
<media-poster>
  <img alt="" />
</media-poster>
```

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

The `<img>` child is optional. Leave it out and `<media-poster>` draws one of its own in its shadow DOM.

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:

```html
<video-player poster="poster.jpg"></video-player>
```

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

`<media-poster>` draws a fallback image in its shadow DOM and fills in its `src`. Put an `<img>` inside it and the element uses yours instead, filling in its `src` the same way:

```html
<media-poster>
  <img alt="" />
</media-poster>
```

Give that image a `src`, a `srcset`, or `<source>` candidates and it is yours; the component leaves it alone:

```html
<media-poster>
  <img src="poster.jpg" srcset="poster-480.jpg 480w, poster-1080.jpg 1080w" alt="Keynote speaker" />
</media-poster>
```

Inside a skin, slot your image instead. The skin carries a plain one that yours replaces:

```html
<video-skin>
  <video src="video.mp4" playsinline></video>
  <img slot="poster" src="poster.jpg" alt="Keynote speaker" />
</video-skin>
```

A skin can only style an `<img>` you slot directly. Wrap one in a `<picture>` or a framework component 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.

```css
media-poster:not([data-visible]) {
  opacity: 0;
}
```

The image the element draws is exposed as a part. An image you supply is an ordinary child, so style it as a descendant:

```css
media-poster::part(image),
media-poster img {
  object-fit: cover;
}
```

From inside a skin’s shadow root, an image slotted from outside needs `::slotted(img)` as well.

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

```html
<media-poster>
  <img src="poster.jpg" alt="Keynote speaker at a conference" />
</media-poster>
```

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

**index.html**

```html
<!-- TODO: add a captions track to the demo. -->
<video-player class="video-player" poster="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" playsinline></video>

    <media-poster class="media-poster">
      <img alt="" />
    </media-poster>

    <media-play-button class="media-play-button">
      <span class="paused">Play</span>
      <span class="playing">Pause</span>
    </media-play-button>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player media-container {
  position: relative;
  display: block;
}

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

.media-poster {
  position: absolute;
  inset: 0;
  pointer-events: none;
  transition: opacity 0.25s;
}

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

.media-poster img {
  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);
}

.media-play-button .paused,
.media-play-button .playing {
  display: none;
}

.media-play-button[data-paused] .paused {
  display: inline;
}

.media-play-button:not([data-paused]) .playing {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/poster';
```

## API Reference

### media-poster

`<media-poster>` — sets `src` on a poster image it does not own.

The image is a child, as in `<picture>`, but sourcing runs the other way around: `<picture>` treats the `src` on its `<img>` as the fallback, while here an image with no source of its own is the one this element fills in. Give the child a `src`, a `srcset`, or `<source>` candidates and it is yours, left alone.

Left empty, the element draws an image of its own in its shadow root. Supply one as a child to describe it or wrap it: `<media-poster><img alt="Keynote speaker"></media-poster>`. Inside a skin, an `<img slot="poster">` of yours replaces the one the skin carries.

#### State

State is reflected as data attributes for CSS styling.

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

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/thumbnail -->

# media-thumbnail

Time-based thumbnail preview component for timeline scrubbing and hover previews

## Quick Start: Video Track

`<media-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:

```html
<video src="video.mp4" crossorigin="anonymous">
  <track
    kind="metadata"
    label="thumbnails"
    src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/storyboard.vtt"
    default
  />
</video>
<media-thumbnail time="12"></media-thumbnail>
```

A same-origin track needs none of this.

## Import

```ts
import '@videojs/html/ui/thumbnail';
```

## Anatomy

```html
<media-thumbnail>
  <img alt="" decoding="async" />
</media-thumbnail>
```

## Behavior

The thumbnail root resolves an image for the current `time`, owns `src` and `srcset` on it, and reports its loading lifecycle.

The `<img>` child is optional: leave it out and `<media-thumbnail>` draws an image of its own in its shadow DOM; supply one to replace it and compose overlays or loading indicators beside it. Any `crossorigin`, `loading`, or `fetchpriority` the supplied image already carries is yours and wins over the element’s own attributes; the rest are filled in.

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 an enclosing player element because it reads track state from the player store. JSON modes (`thumbnails` property) 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:

```ts
const thumbnail = document.querySelector('media-thumbnail');
thumbnail.crossOrigin = null;
```

Leaving the `crossorigin` attribute off is not the opt out. An absent attribute means “follow the media component”; only the property set to `null` opts out.

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:

```css
media-thumbnail[data-hidden] {
  display: none;
}

media-thumbnail[data-loading] {
  opacity: 0.6;
}

media-thumbnail[data-error] {
  outline: 1px solid #ef4444;
}
```

The image the element draws is exposed as a part. An `<img>` you supply is an ordinary child, so style it as a descendant:

```css
media-thumbnail::part(image),
media-thumbnail > img {
  border-radius: 4px;
}
```

The element 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 element and lay overlays over it:

```css
media-thumbnail {
  position: relative;
}

media-thumbnail > .overlay {
  position: absolute;
  inset: 0;
}
```

## Accessibility

`<media-thumbnail>` 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)

**index.html**

```html
<section class="demo">
  <video-player>
    <media-container>
      <video class="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>
      <media-thumbnail class="media-thumbnail" time="12"></media-thumbnail>
    </media-container>
  </video-player>
</section>
```

**index.css**

```css
.demo {
  position: relative;
  display: block;
  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[data-hidden] {
  display: none;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/thumbnail';
```

### JSON Array

**index.html**

```html
<media-thumbnail class="html-thumbnail-json" time="12" style="max-width: 240px"></media-thumbnail>
```

**index.ts**

```ts
import '@videojs/html/ui/thumbnail';

type DemoThumbnailImage = {
  url: string;
  startTime: number;
  endTime?: number;
};

type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };

const initializedDemos = new WeakSet<ThumbnailDemoElement>();

function initializeDemos(): void {
  document.querySelectorAll<ThumbnailDemoElement>('.html-thumbnail-json').forEach((thumbnail) => {
    if (initializedDemos.has(thumbnail)) return;

    initializedDemos.add(thumbnail);
    thumbnail.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,
      },
    ];
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

### JSON Sprite Array

**index.html**

```html
<media-thumbnail class="html-thumbnail-json-sprite" time="12" style="max-width: 240px"></media-thumbnail>
```

**index.ts**

```ts
import '@videojs/html/ui/thumbnail';

type DemoThumbnailImage = {
  url: string;
  startTime: number;
  endTime?: number;
  width?: number;
  height?: number;
  coords?: { x: number; y: number };
};

type ThumbnailDemoElement = HTMLElement & { thumbnails?: DemoThumbnailImage[] };

const initializedDemos = new WeakSet<ThumbnailDemoElement>();

function initializeDemos(): void {
  document.querySelectorAll<ThumbnailDemoElement>('.html-thumbnail-json-sprite').forEach((thumbnail) => {
    if (initializedDemos.has(thumbnail)) return;

    initializedDemos.add(thumbnail);
    thumbnail.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 },
      },
    ];
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

## API Reference

### media-thumbnail

`<media-thumbnail>` — resolves and sizes a time-based thumbnail into an image.

The element owns `src` and `srcset` on the active image. Left empty, it draws an image of its own in its shadow root. Supply an `<img>` child instead — `<media-thumbnail time="12"><img alt=""></media-thumbnail>` — to compose overlays or loading indicators beside the image the element controls. Any `crossorigin`, `loading`, or `fetchpriority` the child already carries wins over the element's own; the rest are filled in. Inside a skin, an `<img slot="thumbnail">` of yours replaces the one the skin carries.

#### 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 reflected as data attributes for CSS styling.

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

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/tooltip -->

# media-tooltip

A tooltip component for displaying contextual labels on hover and focus

## Import

```ts
import '@videojs/html/ui/tooltip';
import '@videojs/html/ui/tooltip-group';
import '@videojs/html/ui/tooltip-label';
import '@videojs/html/ui/tooltip-shortcut';
```

## Anatomy

```html
<media-tooltip-group>
  <button commandfor="my-tooltip">Hover me</button>
  <media-tooltip id="my-tooltip">
    <media-tooltip-label>Label text</media-tooltip-label>
    <media-tooltip-shortcut>K</media-tooltip-shortcut>
  </media-tooltip>
</media-tooltip-group>
```

## 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 `<media-tooltip>` element is the popup itself. Link it to a trigger using the `commandfor` attribute on any button, pointing to the tooltip’s `id`. The element discovers its trigger automatically and manages open/close state and positioning. Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing — the group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.

Tooltips inside a [player container](https://videojs.org/docs/framework/html/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.

`<media-tooltip-group>` coordinates tooltip delay timing only; it does not replace the container’s popup group.

## Styling

Use [CSS custom properties](https://videojs.org/docs/framework/html/reference/components/tooltip#root-css-custom-properties) for positioning offsets:

```css
media-tooltip {
  --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
media-tooltip[data-open] {
  display: block;
}
media-tooltip[data-starting-style] {
  opacity: 0;
}
media-tooltip[data-ending-style] {
  opacity: 0;
}
media-tooltip[data-side="top"] {
  transform-origin: bottom center;
}
media-tooltip[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

**index.html**

```html
<div class="demo">
  <button type="button" commandfor="tooltip-demo" class="trigger">Hover me</button>
  <media-tooltip id="tooltip-demo" class="media-tooltip"> Tooltip content </media-tooltip>
</div>
```

**index.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;
  font-size: 13px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.85);
  border-radius: 6px;
  backdrop-filter: blur(10px);
}
```

**index.ts**

```ts
import '@videojs/html/ui/tooltip';
```

### Grouping

Wrap tooltip trigger/popup pairs in `<media-tooltip-group>` to coordinate timing. The group’s `delay`, `close-delay`, and `timeout` attributes control shared timing for all contained tooltips.

**index.html**

```html
<media-tooltip-group class="demo">
  <button type="button" commandfor="tooltip-play" class="trigger">Play</button>
  <media-tooltip id="tooltip-play" class="media-tooltip">Play video</media-tooltip>

  <button type="button" commandfor="tooltip-mute" class="trigger">Mute</button>
  <media-tooltip id="tooltip-mute" class="media-tooltip">Mute audio</media-tooltip>

  <button type="button" commandfor="tooltip-fullscreen" class="trigger">Fullscreen</button>
  <media-tooltip id="tooltip-fullscreen" class="media-tooltip">Enter fullscreen</media-tooltip>
</media-tooltip-group>
```

**index.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;
  font-size: 13px;
  color: white;
  white-space: nowrap;
  pointer-events: none;
  background: rgba(0, 0, 0, 0.85);
  border-radius: 6px;
  backdrop-filter: blur(10px);
}
```

**index.ts**

```ts
import '@videojs/html/ui/tooltip';
import '@videojs/html/ui/tooltip-group';
```

## API Reference

### media-tooltip-group

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` (attribute `close-delay`) | `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. |

### media-tooltip

#### 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` (attribute `close-delay`) | `number` | `0` | Delay in ms before closing after pointer leaves. |
| `defaultOpen` (attribute `default-open`) | `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` (attribute `disable-hoverable-popup`) | `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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `open-change` | Fired when the tooltip's open state changes. |

### media-tooltip-label

Label region inside `media-tooltip`; parent syncs text from the trigger when linked to a media button.

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

### media-tooltip-shortcut

Shortcut hint inside `media-tooltip`. CSS skins: `class="media-tooltip__kbd"`; Tailwind skins: `class` from `popup.tooltipShortcut`.

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

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/buffering-indicator -->

# media-buffering-indicator

Loading indicator that displays when the video player is buffering or waiting for data

## Import

```ts
import '@videojs/html/ui/buffering-indicator';
```

## Anatomy

```html
<media-buffering-indicator></media-buffering-indicator>
```

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

**index.html**

```html
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-buffering-indicator class="media-buffering-indicator">
      <div class="spinner"></div>
    </media-buffering-indicator>
  </media-container>
</video-player>
```

**index.css**

```css
.video-player 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);
  }
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/buffering-indicator';
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `delay` | `number` | `500` | Delay in milliseconds before the indicator becomes visible. |

### State

State is reflected as data attributes for CSS styling.

| 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/html/reference/components/seek-indicator -->

# media-seek-indicator

A temporary visual indicator for keyboard and gesture seeking

## Import

```ts
import '@videojs/html/ui/seek-indicator';
import '@videojs/html/ui/seek-indicator-value';
```

## Anatomy

```html
<media-seek-indicator>
  <media-seek-indicator-value></media-seek-indicator-value>
</media-seek-indicator>
```

## Behavior

`<media-seek-indicator>` displays feedback for seek actions emitted by a [`<media-hotkey>`](https://videojs.org/docs/framework/html/reference/components/hotkey) or [`<media-gesture>`](https://videojs.org/docs/framework/html/reference/components/gesture) in the same player `<media-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 `<media-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.

The element remains in the document with `hidden` until the next handled seek action.

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

```css
media-seek-indicator[data-direction="backward"] {
  left: 1rem;
}

media-seek-indicator[data-direction="forward"] {
  right: 1rem;
}

media-seek-indicator[data-starting-style],
media-seek-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`<media-seek-indicator>` is visual feedback and does not create a live region. Keep the same seek operation available through keyboard-operable controls, and pair it with [`<media-status-announcer>`](https://videojs.org/docs/framework/html/reference/components/status-announcer) when changes should be announced to screen readers. Do not make `<media-seek-indicator-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.

**index.html**

```html
<video-player>
  <media-container class="html-seek-indicator-basic" tabindex="0">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <p class="html-seek-indicator-basic__instructions">Focus the player · ←/→: seek 10s · 0–9: seek to percent</p>
    <media-seek-indicator class="html-seek-indicator-basic__indicator" aria-hidden="true">
      <media-seek-indicator-value class="html-seek-indicator-basic__value"></media-seek-indicator-value>
    </media-seek-indicator>
    <media-hotkey keys="ArrowLeft" action="seekStep" value="-10"></media-hotkey>
    <media-hotkey keys="ArrowRight" action="seekStep" value="10"></media-hotkey>
    <media-hotkey keys="0-9" action="seekToPercent"></media-hotkey>
  </media-container>
</video-player>
```

**index.css**

```css
.html-seek-indicator-basic {
  position: relative;
}

.html-seek-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.html-seek-indicator-basic video {
  display: block;
  width: 100%;
}

.html-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%;
}

.html-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;
}

.html-seek-indicator-basic__indicator::before {
  font-size: 24px;
  line-height: 1;
  content: "↔";
}

.html-seek-indicator-basic__indicator[data-direction="backward"] {
  right: auto;
  left: 16px;
  transform: translateY(-50%);
}

.html-seek-indicator-basic__indicator[data-direction="backward"]::before {
  content: "↶";
}

.html-seek-indicator-basic__indicator[data-direction="forward"] {
  right: 16px;
  left: auto;
  transform: translateY(-50%);
}

.html-seek-indicator-basic__indicator[data-direction="forward"]::before {
  content: "↷";
}

.html-seek-indicator-basic__indicator[data-starting-style],
.html-seek-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

.html-seek-indicator-basic__value {
  font-variant-numeric: tabular-nums;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/seek-indicator';
import '@videojs/html/ui/seek-indicator-value';
```

## API Reference

### media-seek-indicator

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |

#### State

State is reflected as data attributes for CSS styling.

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

### media-seek-indicator-value

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/status-indicator -->

# media-status-indicator

Display temporary visual feedback for keyboard and gesture actions

## Import

```ts
import '@videojs/html/ui/status-indicator';
import '@videojs/html/ui/status-indicator-value';
```

## Anatomy

```html
<media-status-indicator>
  <media-status-indicator-value></media-status-indicator-value>
</media-status-indicator>
```

## Behavior

`<media-status-indicator>` displays feedback for actions emitted by a [`<media-hotkey>`](https://videojs.org/docs/framework/html/reference/components/hotkey) or [`<media-gesture>`](https://videojs.org/docs/framework/html/reference/components/gesture) in the same player `<media-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/html/reference/components/status-indicator#custom-actions).

Use `actions` to allow only some of the supported actions. Omitting it allows all supported actions.

Set the `actions` attribute to action names separated by commas, whitespace, or both:

```html
<media-status-indicator actions="togglePaused, toggleMuted">
  <media-status-indicator-value></media-status-indicator-value>
</media-status-indicator>
```

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.

The element remains in the document with `hidden` until the next handled action.

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

`deriveCustomStatus` is a JavaScript property with no attribute:

```ts
const rates = [0.5, 1, 1.5, 2];
const indicator = document.querySelector("media-status-indicator");

function getNextRate(rate = 1) {
  const index = rates.indexOf(rate);

  return rates[Math.min(index + 1, rates.length - 1)] ?? rate;
}

indicator.deriveCustomStatus = (event, snapshot) =>
  event.action === "stepRate"
    ? { status: "rate-up", label: `${getNextRate(snapshot.playbackRate)}×`, value: null }
    : null;
```

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

```css
media-status-indicator[data-status="play"] {
  color: green;
}

media-status-indicator[data-starting-style],
media-status-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`<media-status-indicator>` is visual feedback and does not create a live region. Keep every action available through keyboard-operable controls, and pair the player with [`<media-status-announcer>`](https://videojs.org/docs/framework/html/reference/components/status-announcer) when state changes should be announced to screen readers. Do not make `<media-status-indicator-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.

**index.html**

```html
<video-player>
  <media-container class="html-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 class="html-status-indicator-basic__instructions">
      Focus the player · K: play/pause · M: mute · F: fullscreen · C: captions · I: picture-in-picture
    </p>
    <media-status-indicator
      class="html-status-indicator-basic__indicator"
      actions="togglePaused toggleMuted toggleSubtitles toggleFullscreen togglePictureInPicture"
      aria-hidden="true"
    >
      <media-status-indicator-value class="html-status-indicator-basic__value"></media-status-indicator-value>
    </media-status-indicator>
    <media-hotkey keys="k" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
    <media-hotkey keys="c" action="toggleSubtitles"></media-hotkey>
    <media-hotkey keys="i" action="togglePictureInPicture"></media-hotkey>
  </media-container>
</video-player>
```

**index.css**

```css
.html-status-indicator-basic {
  position: relative;
}

.html-status-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.html-status-indicator-basic video {
  display: block;
  width: 100%;
}

.html-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;
}

.html-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;
}

.html-status-indicator-basic__indicator::before {
  font-size: 28px;
  font-weight: 700;
  line-height: 1;
}

.html-status-indicator-basic__indicator[data-status="play"]::before {
  content: "▶";
}

.html-status-indicator-basic__indicator[data-status="pause"]::before {
  content: "Ⅱ";
}

.html-status-indicator-basic__indicator[data-status="volume-off"]::before {
  content: "🔇";
}

.html-status-indicator-basic__indicator[data-status="volume-low"]::before {
  content: "🔉";
}

.html-status-indicator-basic__indicator[data-status="volume-high"]::before {
  content: "🔊";
}

.html-status-indicator-basic__indicator[data-status="captions-on"]::before,
.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
  content: "CC";
}

.html-status-indicator-basic__indicator[data-status="captions-off"]::before {
  text-decoration: line-through;
}

.html-status-indicator-basic__indicator[data-status="fullscreen"]::before {
  content: "⛶";
}

.html-status-indicator-basic__indicator[data-status="exit-fullscreen"]::before {
  content: "⊠";
}

.html-status-indicator-basic__indicator[data-status="pip"]::before,
.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  content: "▣";
}

.html-status-indicator-basic__indicator[data-status="exit-pip"]::before {
  text-decoration: line-through;
}

.html-status-indicator-basic__indicator[data-starting-style],
.html-status-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

.html-status-indicator-basic__value {
  margin-top: 8px;
  font-variant-numeric: tabular-nums;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/status-indicator';
import '@videojs/html/ui/status-indicator-value';
```

## API Reference

### media-status-indicator

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `readonly InputAction[]` | — | Input actions allowed to open the indicator. All supported actions are allowed when omitted. |
| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |
| `deriveCustomStatus` (attribute `derive-custom-status`) | `((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. |

#### State

State is reflected as data attributes for CSS styling.

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

### media-status-indicator-value

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/volume-indicator -->

# media-volume-indicator

Display temporary visual feedback for keyboard and gesture volume actions

## Import

```ts
import '@videojs/html/ui/volume-indicator';
import '@videojs/html/ui/volume-indicator-fill';
import '@videojs/html/ui/volume-indicator-value';
```

## Anatomy

```html
<media-volume-indicator>
  <media-volume-indicator-fill>
    <media-volume-indicator-value></media-volume-indicator-value>
  </media-volume-indicator-fill>
</media-volume-indicator>
```

## Behavior

`<media-volume-indicator>` displays feedback for `toggleMuted` and `volumeStep` actions emitted by a [`<media-hotkey>`](https://videojs.org/docs/framework/html/reference/components/hotkey) or [`<media-gesture>`](https://videojs.org/docs/framework/html/reference/components/gesture) in the same player `<media-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 |

`<media-volume-indicator-value>` displays the rounded percentage from 0% through 100%. `<media-volume-indicator-fill>` receives the same percentage through `--media-volume-fill`. Nest the value inside the 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.

The element remains in the document with `hidden` until the next handled action.

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 `<media-volume-indicator-fill>`, not `<media-volume-indicator>`. Read it from a fill selector when sizing a progress treatment.

```css
media-volume-indicator-fill::before {
  width: var(--media-volume-fill, 0%);
}

media-volume-indicator[data-starting-style],
media-volume-indicator[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

`<media-volume-indicator>` is visual feedback and does not create a live region. Keep volume and mute available through keyboard-operable controls, and pair the player with [`<media-status-announcer>`](https://videojs.org/docs/framework/html/reference/components/status-announcer) when state changes should be announced to screen readers. Do not make `<media-volume-indicator-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%.

**index.html**

```html
<video-player>
  <media-container class="html-volume-indicator-basic" tabindex="0">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <p class="html-volume-indicator-basic__instructions">Focus the player · M: mute · ↑/↓: volume ±5%</p>
    <media-volume-indicator class="html-volume-indicator-basic__indicator" aria-hidden="true">
      <media-volume-indicator-fill class="html-volume-indicator-basic__fill">
        <media-volume-indicator-value class="html-volume-indicator-basic__value"></media-volume-indicator-value>
      </media-volume-indicator-fill>
    </media-volume-indicator>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="ArrowUp" action="volumeStep" value="0.05"></media-hotkey>
    <media-hotkey keys="ArrowDown" action="volumeStep" value="-0.05"></media-hotkey>
  </media-container>
</video-player>
```

**index.css**

```css
.html-volume-indicator-basic {
  position: relative;
}

.html-volume-indicator-basic:focus-visible {
  outline: 3px solid #60a5fa;
  outline-offset: 2px;
}

.html-volume-indicator-basic video {
  display: block;
  width: 100%;
}

.html-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%;
}

.html-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;
}

.html-volume-indicator-basic__indicator::before {
  margin-bottom: 12px;
  font-size: 28px;
  line-height: 1;
}

.html-volume-indicator-basic__indicator[data-level="off"]::before {
  content: "🔇";
}

.html-volume-indicator-basic__indicator[data-level="low"]::before {
  content: "🔉";
}

.html-volume-indicator-basic__indicator[data-level="high"]::before {
  content: "🔊";
}

.html-volume-indicator-basic__fill {
  position: relative;
  width: 180px;
  height: 10px;
  background: rgb(255 255 255 / 25%);
  border-radius: 9999px;
}

.html-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;
}

.html-volume-indicator-basic__value {
  position: absolute;
  top: calc(100% + 6px);
  left: 50%;
  font-variant-numeric: tabular-nums;
  translate: -50%;
}

.html-volume-indicator-basic__indicator[data-starting-style],
.html-volume-indicator-basic__indicator[data-ending-style] {
  opacity: 0;
  scale: 0.85;
}

@media (prefers-reduced-motion: no-preference) {
  .html-volume-indicator-basic__indicator[data-min],
  .html-volume-indicator-basic__indicator[data-max] {
    animation: html-volume-indicator-basic-shake 300ms linear;
  }
}

@keyframes html-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%;
  }
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/volume-indicator';
import '@videojs/html/ui/volume-indicator-fill';
import '@videojs/html/ui/volume-indicator-value';

const initializedVideos = new WeakSet<HTMLVideoElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLVideoElement>('.html-volume-indicator-basic video').forEach((video) => {
    if (initializedVideos.has(video)) return;

    initializedVideos.add(video);
    video.volume = 0.5;
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

## API Reference

### media-volume-indicator

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the indicator closes. |

#### State

State is reflected as data attributes for CSS styling.

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

### media-volume-indicator-fill

### media-volume-indicator-value

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/dialog -->

# media-dialog

A modal dialog for application content, including players opened from a thumbnail

## Import

```ts
import '@videojs/html/ui/dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';
```

## Anatomy

```html
<button commandfor="video-dialog">Open video</button>
<media-dialog id="video-dialog">
  <media-dialog-backdrop></media-dialog-backdrop>
  <media-dialog-popup>
    <media-dialog-title></media-dialog-title>
    <media-dialog-description></media-dialog-description>
    <media-dialog-close></media-dialog-close>
  </media-dialog-popup>
</media-dialog>
```

## Behavior

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

Place a button immediately before `media-dialog`, or connect them explicitly with `commandfor` and an `id`. You can also set the dialog’s `open` property directly. The root provides state without creating a layout box; `media-dialog-backdrop` and `media-dialog-popup` are sibling surfaces. The element dispatches `open-change` when its state changes and `open-change-complete` after the popup transition finishes.

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 [`<media-alert-dialog>`](https://videojs.org/docs/framework/html/reference/components/alert-dialog) for urgent messages that require acknowledgement. [`<media-error-dialog>`](https://videojs.org/docs/framework/html/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 |

```css
media-dialog-backdrop:not([data-open]),
media-dialog-popup:not([data-open]) {
  display: none;
}

media-dialog-backdrop[data-starting-style],
media-dialog-backdrop[data-ending-style],
media-dialog-popup[data-starting-style],
media-dialog-popup[data-ending-style] {
  opacity: 0;
}
```

## Accessibility

The popup uses `role="dialog"` and `aria-modal="true"`. Include `<media-dialog-title>` so the dialog always has an accessible name. `<media-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.

**index.html**

```html
<div class="html-dialog-basic">
  <button class="html-dialog-basic__trigger" type="button" commandfor="html-video-dialog">
    <img src="https://image.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/thumbnail.jpg" alt="" />
    <span>Play the video</span>
  </button>
  <media-dialog id="html-video-dialog">
    <media-dialog-backdrop class="html-dialog-basic__backdrop"></media-dialog-backdrop>
    <media-dialog-popup class="html-dialog-basic__dialog">
      <div class="html-dialog-basic__popup">
        <media-dialog-title class="html-dialog-basic__title">Video title</media-dialog-title>
        <media-dialog-description class="html-dialog-basic__description">
          A video opened from a thumbnail.
        </media-dialog-description>
        <media-dialog-close class="html-dialog-basic__close">Close</media-dialog-close>
        <video-player>
          <media-container>
            <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" controls muted playsinline></video>
          </media-container>
        </video-player>
      </div>
    </media-dialog-popup>
  </media-dialog>
</div>
```

**index.css**

```css
.html-dialog-basic {
  position: relative;
  min-height: 320px;
}

.html-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;
}

.html-dialog-basic__trigger img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.html-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  z-index: 1;
  background: rgb(3 7 18 / 80%);
  transition: opacity 200ms ease;
}

.html-dialog-basic__dialog {
  position: absolute;
  inset: 0;
  z-index: 2;
  display: flex;
  align-items: center;
  justify-content: center;
  padding: 20px;
  transition: opacity 150ms ease;
}

.html-dialog-basic__backdrop:not([data-open]),
.html-dialog-basic__dialog:not([data-open]) {
  display: none;
}

.html-dialog-basic__backdrop[data-starting-style],
.html-dialog-basic__backdrop[data-ending-style],
.html-dialog-basic__dialog[data-starting-style],
.html-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.html-dialog-basic__popup {
  position: relative;
  width: 100%;
  max-width: 560px;
  padding: 16px;
  color: white;
  background: #111827;
  border-radius: 12px;
}

.html-dialog-basic__title {
  display: block;
  margin-bottom: 4px;
  font-size: 1.125rem;
  font-weight: 600;
}

.html-dialog-basic__description {
  display: block;
  margin-bottom: 12px;
}

.html-dialog-basic__close {
  position: absolute;
  top: 12px;
  right: 12px;
  padding: 6px 12px;
  color: #111827;
  cursor: pointer;
  background: white;
  border: 0;
  border-radius: 9999px;
}

.html-dialog-basic video {
  display: block;
  width: 100%;
}

@media (prefers-reduced-motion: reduce) {
  .html-dialog-basic__backdrop,
  .html-dialog-basic__dialog {
    transition: none;
  }
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';

const initializedDemos = new WeakSet<HTMLElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLElement>('.html-dialog-basic').forEach((demo) => {
    if (initializedDemos.has(demo)) return;

    initializedDemos.add(demo);

    const dialog = demo.querySelector('media-dialog');
    const video = demo.querySelector('video');

    dialog?.addEventListener('open-change', (event) => {
      if (!video) return;

      // SAFETY: `media-dialog` defines `open-change` with an `{ open }` detail payload.
      const { open } = (event as CustomEvent<{ open: boolean }>).detail;

      if (open) void video.play().catch(() => {});
      else video.pause();
    });
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

## API Reference

### media-dialog

Manages dialog state and provides it to the compound parts.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | `true` | Whether pressing Escape closes the dialog. |
| `defaultOpen` (attribute `default-open`) | `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 reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `open-change` | |
| `open-change-complete` | |

### media-dialog-backdrop

Presentational backdrop that reflects its owning dialog's 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. |

### media-dialog-close

Button that closes its owning dialog; the element itself takes `role="button"` and keyboard focus.

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

### media-dialog-description

Text announced as its owning dialog's description. The element takes the `id` that the popup's `aria-describedby` points to.

### media-dialog-popup

Semantic popup that owns focus management and dialog transition completion.

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

### media-dialog-title

Text that labels its owning dialog. The element takes the `id` that the popup's `aria-labelledby` points to.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/alert-dialog -->

# media-alert-dialog

A modal alert dialog for urgent messages that require acknowledgement

## Import

```ts
import '@videojs/html/ui/alert-dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';
```

## Anatomy

```html
<media-alert-dialog>
  <media-dialog-backdrop></media-dialog-backdrop>
  <media-dialog-popup>
    <media-dialog-title></media-dialog-title>
    <media-dialog-description></media-dialog-description>
    <media-dialog-close></media-dialog-close>
  </media-dialog-popup>
</media-alert-dialog>
```

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

`<media-alert-dialog>` adds alert semantics, while the other parts are the same elements [`<media-dialog>`](https://videojs.org/docs/framework/html/reference/components/dialog) uses. For general modal content, including a player opened from a thumbnail, use `<media-dialog>` instead.

Set the root’s `open` property to show the dialog. The root supplies alert state while the shared `media-dialog-backdrop` and `media-dialog-popup` siblings render the visual surfaces and semantics. The root updates the property and dispatches `open-change` when the dialog closes.

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 |

```css
media-dialog-backdrop:not([data-open]),
media-dialog-popup:not([data-open]) {
  display: none;
}

media-dialog-backdrop[data-starting-style],
media-dialog-backdrop[data-ending-style],
media-dialog-popup[data-starting-style],
media-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

**index.html**

```html
<div class="html-alert-dialog-basic">
  <button class="html-alert-dialog-basic__trigger" type="button">Open alert dialog</button>
  <media-alert-dialog>
    <media-dialog-backdrop class="html-alert-dialog-basic__backdrop"></media-dialog-backdrop>
    <media-dialog-popup class="html-alert-dialog-basic__dialog">
      <media-dialog-title class="html-alert-dialog-basic__title">Stop playback?</media-dialog-title>
      <media-dialog-description class="html-alert-dialog-basic__description">
        Your current playback position will be lost.
      </media-dialog-description>
      <media-dialog-close class="html-alert-dialog-basic__close">Continue</media-dialog-close>
    </media-dialog-popup>
  </media-alert-dialog>
</div>
```

**index.css**

```css
.html-alert-dialog-basic {
  position: relative;
  display: grid;
  place-items: center;
  min-height: 240px;
  overflow: hidden;
  background: #111827;
  border-radius: 12px;
}

.html-alert-dialog-basic__trigger,
.html-alert-dialog-basic__close {
  padding: 8px 16px;
  color: #111827;
  cursor: pointer;
  background: #fff;
  border: 0;
  border-radius: 9999px;
}

.html-alert-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  background: rgb(3 7 18 / 92%);
  transition: opacity 150ms ease;
}

.html-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;
}

.html-alert-dialog-basic__backdrop:not([data-open]),
.html-alert-dialog-basic__dialog:not([data-open]) {
  display: none;
}

.html-alert-dialog-basic__backdrop[data-starting-style],
.html-alert-dialog-basic__backdrop[data-ending-style],
.html-alert-dialog-basic__dialog[data-starting-style],
.html-alert-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.html-alert-dialog-basic__title,
.html-alert-dialog-basic__description {
  display: block;
}

.html-alert-dialog-basic__title {
  font-size: 20px;
  font-weight: 600;
}

.html-alert-dialog-basic__description {
  color: #d1d5db;
}

.html-alert-dialog-basic__close {
  justify-self: center;
}
```

**index.ts**

```ts
import '@videojs/html/ui/alert-dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';

const initializedDemos = new WeakSet<HTMLElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLElement>('.html-alert-dialog-basic').forEach((demo) => {
    if (initializedDemos.has(demo)) return;

    initializedDemos.add(demo);

    const trigger = demo.querySelector<HTMLButtonElement>('.html-alert-dialog-basic__trigger');
    const dialog = demo.querySelector('media-alert-dialog');

    trigger?.addEventListener('click', () => {
      if (dialog) dialog.open = true;
    });
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

## API Reference

### media-alert-dialog

A modal dialog with alert semantics.

#### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeOnEscape` (attribute `close-on-escape`) | `boolean` | — | Whether pressing Escape closes the dialog. |
| `defaultOpen` (attribute `default-open`) | `boolean` | — | Initial open state for uncontrolled usage. |
| `open` | `boolean` | — | Controlled open state. When set, the consumer is responsible for toggling. |

#### State

State is reflected as data attributes for CSS styling.

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

#### Events

| Event | Description |
| --- | --- |
| `open-change` | Fired when the dialog's open state changes. |
| `open-change-complete` | |

### media-dialog-backdrop

Presentational backdrop that reflects its owning dialog's 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. |

### media-dialog-close

Button that closes its owning dialog; the element itself takes `role="button"` and keyboard focus.

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

### media-dialog-description

Text announced as its owning dialog's description. The element takes the `id` that the popup's `aria-describedby` points to.

### media-dialog-popup

Semantic popup that owns focus management and dialog transition completion.

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

### media-dialog-title

Text that labels its owning dialog. The element takes the `id` that the popup's `aria-labelledby` points to.

---

<!-- Source: https://videojs.org/docs/framework/html/reference/components/error-dialog -->

# media-error-dialog

An alert dialog that presents and dismisses playback errors

## Import

```ts
import '@videojs/html/ui/error-dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';
```

## Anatomy

```html
<media-error-dialog>
  <media-dialog-backdrop></media-dialog-backdrop>
  <media-dialog-popup>
    <media-dialog-title></media-dialog-title>
    <media-dialog-description></media-dialog-description>
    <media-dialog-close></media-dialog-close>
  </media-dialog-popup>
</media-error-dialog>
```

## Behavior

`<media-error-dialog>` is a specialized root driven by the player’s [error feature](https://videojs.org/docs/framework/html/reference/api/feature-error). It uses alert semantics and reuses the backdrop, popup, title, description, and close parts from [`<media-dialog>`](https://videojs.org/docs/framework/html/reference/components/dialog); it is not nested inside `<media-alert-dialog>`. 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.

```css
media-dialog-backdrop:not([data-open]),
media-dialog-popup:not([data-open]) {
  display: none;
}

media-dialog-backdrop[data-starting-style],
media-dialog-backdrop[data-ending-style],
media-dialog-popup[data-starting-style],
media-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

**index.html**

```html
<video-player class="html-error-dialog-basic">
  <media-container class="html-error-dialog-basic__container">
    <video
      class="html-error-dialog-basic__video"
      src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"
      autoplay
      muted
      playsinline
      loop
    ></video>
    <button class="html-error-dialog-basic__trigger" type="button">Trigger a playback error</button>
    <media-error-dialog>
      <media-dialog-backdrop class="html-error-dialog-basic__backdrop"></media-dialog-backdrop>
      <media-dialog-popup class="html-error-dialog-basic__dialog">
        <media-dialog-title class="html-error-dialog-basic__title"></media-dialog-title>
        <media-dialog-description class="html-error-dialog-basic__description"></media-dialog-description>
        <media-dialog-close class="html-error-dialog-basic__close"></media-dialog-close>
      </media-dialog-popup>
    </media-error-dialog>
  </media-container>
</video-player>
```

**index.css**

```css
.html-error-dialog-basic__container {
  position: relative;
  display: block;
  overflow: hidden;
  border-radius: 12px;
}

.html-error-dialog-basic__video {
  display: block;
  width: 100%;
}

.html-error-dialog-basic__trigger,
.html-error-dialog-basic__close {
  padding: 8px 16px;
  color: #111827;
  cursor: pointer;
  background: #fff;
  border: 0;
  border-radius: 9999px;
}

.html-error-dialog-basic__trigger {
  position: absolute;
  bottom: 16px;
  left: 16px;
}

.html-error-dialog-basic__backdrop {
  position: absolute;
  inset: 0;
  background: rgb(3 7 18 / 92%);
  transition: opacity 150ms ease;
}

.html-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;
}

.html-error-dialog-basic__backdrop:not([data-open]),
.html-error-dialog-basic__dialog:not([data-open]) {
  display: none;
}

.html-error-dialog-basic__backdrop[data-starting-style],
.html-error-dialog-basic__backdrop[data-ending-style],
.html-error-dialog-basic__dialog[data-starting-style],
.html-error-dialog-basic__dialog[data-ending-style] {
  opacity: 0;
}

.html-error-dialog-basic__title,
.html-error-dialog-basic__description {
  display: block;
}

.html-error-dialog-basic__title {
  font-size: 20px;
  font-weight: 600;
}

.html-error-dialog-basic__description {
  color: #d1d5db;
}

.html-error-dialog-basic__close {
  justify-self: center;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/error-dialog';
import '@videojs/html/ui/dialog-backdrop';
import '@videojs/html/ui/dialog-popup';
import '@videojs/html/ui/dialog-title';
import '@videojs/html/ui/dialog-description';
import '@videojs/html/ui/dialog-close';

const brokenSource = 'data:video/mp4;base64,AAAA';
const initializedDemos = new WeakSet<HTMLElement>();

function initializeDemos(): void {
  document.querySelectorAll<HTMLElement>('.html-error-dialog-basic').forEach((demo) => {
    if (initializedDemos.has(demo)) return;

    initializedDemos.add(demo);

    const video = demo.querySelector('video');
    const trigger = demo.querySelector<HTMLButtonElement>('.html-error-dialog-basic__trigger');

    trigger?.addEventListener('click', () => {
      if (!video) return;

      video.src = brokenSource;
      video.load();
    });
  });
}

initializeDemos();
document.addEventListener('astro:page-load', initializeDemos);
```

## API Reference

### media-error-dialog

Opens from player error state and provides it to the shared dialog parts.

#### State

State is reflected as data attributes for CSS styling.

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

### media-dialog-backdrop

Presentational backdrop that reflects its owning dialog's 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. |

### media-dialog-popup

Semantic popup that owns focus management and dialog transition completion.

#### 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/html/reference/components/gesture -->

# media-gesture

Map tap and double-tap gestures to player actions

## Import

```ts
import '@videojs/html/ui/gesture';
```

## Anatomy

```html
<media-gesture
  type="doubletap"
  region="right"
  pointer="touch"
  action="seekStep"
  value="10"
></media-gesture>
```

## Behavior

`<media-gesture>` is a behavior component: it renders no visible interface. Place it inside a [`<media-container>`](https://videojs.org/docs/framework/html/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.

**index.html**

```html
<video-player>
  <media-container class="html-gesture-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
    <p class="html-gesture-basic__instructions">Click: play/pause · Double-click: −10s · fullscreen · +10s</p>
    <media-play-button class="html-gesture-basic__button">
      <span class="show-when-paused">Play</span>
      <span class="show-when-playing">Pause</span>
      <span class="show-when-ended">Replay</span>
    </media-play-button>
    <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
    <media-gesture type="doubletap" action="toggleFullscreen" region="center"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>
  </media-container>
</video-player>
```

**index.css**

```css
.html-gesture-basic {
  position: relative;
}

.html-gesture-basic video {
  width: 100%;
}

.html-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;
}

.html-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;
}

.html-gesture-basic__button .show-when-paused,
.html-gesture-basic__button .show-when-playing,
.html-gesture-basic__button .show-when-ended {
  display: none;
}

.html-gesture-basic__button[data-paused]:not([data-ended]) .show-when-paused,
.html-gesture-basic__button:not([data-paused]) .show-when-playing,
.html-gesture-basic__button[data-ended] .show-when-ended {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/gesture';
import '@videojs/html/ui/play-button';
```

## 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/html/reference/components/hotkey -->

# media-hotkey

Register a keyboard shortcut that invokes a player action

## Import

```ts
import '@videojs/html/ui/hotkey';
```

## Anatomy

```html
<media-hotkey keys="Space" action="togglePaused"></media-hotkey>
```

## Behavior

`<media-hotkey>` is a behavior component: it renders no visible interface. Place it inside a [`<media-container>`](https://videojs.org/docs/framework/html/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.

**index.html**

```html
<video-player>
  <media-container class="html-hotkey-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
    <p class="html-hotkey-basic__instructions">Space: play/pause · M: mute · ←/→: seek</p>
    <media-play-button class="html-hotkey-basic__button">
      <span class="show-when-paused">Play</span>
      <span class="show-when-playing">Pause</span>
      <span class="show-when-ended">Replay</span>
    </media-play-button>
    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
  </media-container>
</video-player>
```

**index.css**

```css
.html-hotkey-basic {
  position: relative;
}

.html-hotkey-basic video {
  width: 100%;
}

.html-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;
}

.html-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;
}

.html-hotkey-basic__button .show-when-paused,
.html-hotkey-basic__button .show-when-playing,
.html-hotkey-basic__button .show-when-ended {
  display: none;
}

.html-hotkey-basic__button[data-paused]:not([data-ended]) .show-when-paused,
.html-hotkey-basic__button:not([data-paused]) .show-when-playing,
.html-hotkey-basic__button[data-ended] .show-when-ended {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/play-button';
```

## 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/html/reference/components/status-announcer -->

# media-status-announcer

Announce player state changes through a persistent status live region

## Import

```ts
import '@videojs/html/ui/status-announcer';
```

## Anatomy

```html
<media-status-announcer></media-status-announcer>
```

## Behavior

`<media-status-announcer>` watches player-store snapshots, so it reports changes made by buttons, sliders, custom controls, or direct player actions. It does not depend on [`<media-hotkey>`](https://videojs.org/docs/framework/html/reference/components/hotkey) or [`<media-gesture>`](https://videojs.org/docs/framework/html/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.

The custom element receives labels from the nearest player i18n context.

## Styling

`<media-status-announcer>` 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.

```css
media-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 `<media-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 [`<media-seek-indicator>`](https://videojs.org/docs/framework/html/reference/components/seek-indicator) for temporary visual seek feedback. Keep that visual value out of a live region; `<media-status-announcer>` 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 `<media-status-announcer>` suppresses its duplicate volume and completed-seek message.

**index.html**

```html
<video-player>
  <media-container class="html-status-announcer-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
    <p class="html-status-announcer-basic__instructions">These controls announce status changes to screen readers.</p>
    <div class="html-status-announcer-basic__controls">
      <media-play-button class="html-status-announcer-basic__button">
        <span class="show-when-paused">Play</span>
        <span class="show-when-playing">Pause</span>
        <span class="show-when-ended">Replay</span>
      </media-play-button>
      <media-mute-button class="html-status-announcer-basic__button">
        <span class="show-when-muted">Unmute</span>
        <span class="show-when-unmuted">Mute</span>
      </media-mute-button>
      <media-volume-slider class="html-status-announcer-basic__volume-slider">
        <media-slider-track class="html-status-announcer-basic__track">
          <media-slider-fill class="html-status-announcer-basic__fill"></media-slider-fill>
        </media-slider-track>
        <media-slider-thumb class="html-status-announcer-basic__thumb"></media-slider-thumb>
      </media-volume-slider>
    </div>
    <media-time-slider class="html-status-announcer-basic__time-slider">
      <media-slider-track class="html-status-announcer-basic__track">
        <media-slider-buffer class="html-status-announcer-basic__buffer"></media-slider-buffer>
        <media-slider-fill class="html-status-announcer-basic__fill"></media-slider-fill>
      </media-slider-track>
      <media-slider-thumb class="html-status-announcer-basic__thumb"></media-slider-thumb>
    </media-time-slider>
    <media-status-announcer class="html-status-announcer-basic__announcer"></media-status-announcer>
  </media-container>
</video-player>
```

**index.css**

```css
.html-status-announcer-basic {
  position: relative;
}

.html-status-announcer-basic video {
  display: block;
  width: 100%;
}

.html-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;
}

.html-status-announcer-basic__controls {
  position: absolute;
  right: 12px;
  bottom: 36px;
  left: 12px;
  display: flex;
  gap: 8px;
  align-items: center;
}

.html-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;
}

.html-status-announcer-basic__button .show-when-paused,
.html-status-announcer-basic__button .show-when-playing,
.html-status-announcer-basic__button .show-when-ended,
.html-status-announcer-basic__button .show-when-muted,
.html-status-announcer-basic__button .show-when-unmuted {
  display: none;
}

.html-status-announcer-basic__button[data-paused]:not([data-ended]) .show-when-paused,
.html-status-announcer-basic__button:not([data-paused]) .show-when-playing,
.html-status-announcer-basic__button[data-ended] .show-when-ended,
.html-status-announcer-basic__button[data-muted] .show-when-muted,
.html-status-announcer-basic__button:not([data-muted]) .show-when-unmuted {
  display: inline;
}

.html-status-announcer-basic__volume-slider,
.html-status-announcer-basic__time-slider {
  position: relative;
  display: flex;
  align-items: center;
  height: 20px;
  cursor: pointer;
}

.html-status-announcer-basic__volume-slider {
  width: 100px;
}

.html-status-announcer-basic__time-slider {
  position: absolute;
  right: 12px;
  bottom: 8px;
  left: 12px;
}

.html-status-announcer-basic__track {
  position: absolute;
  right: 0;
  left: 0;
  height: 5px;
  overflow: hidden;
  background: rgb(255 255 255 / 30%);
  border-radius: 9999px;
}

.html-status-announcer-basic__buffer,
.html-status-announcer-basic__fill {
  position: absolute;
  top: 0;
  left: 0;
  height: 100%;
  border-radius: inherit;
}

.html-status-announcer-basic__buffer {
  width: var(--media-slider-buffer);
  background: rgb(255 255 255 / 30%);
}

.html-status-announcer-basic__fill {
  width: var(--media-slider-fill);
  background: white;
}

.html-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%;
}

.html-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%);
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/mute-button';
import '@videojs/html/ui/play-button';
import '@videojs/html/ui/status-announcer';
import '@videojs/html/ui/time-slider';
import '@videojs/html/ui/slider-track';
import '@videojs/html/ui/slider-buffer';
import '@videojs/html/ui/slider-fill';
import '@videojs/html/ui/slider-thumb';
import '@videojs/html/ui/volume-slider';
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` (attribute `close-delay`) | `number` | — | Delay in milliseconds before the current announcement label is cleared. |

### State

State is reflected as data attributes for CSS styling.

| 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/html/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=html) imports its icons from these modules, and your own controls can use them too.

Each icon is available as an SVG string and by name through the `<media-icon>` element.

## Import

Register `<media-icon>`:

```ts
import "@videojs/html/icons/element";
```

Or import SVG strings:

```ts
import { playIcon } from "@videojs/html/icons";
```

## Icon sets

Three sets ship with the same icon names and different designs.

| Set | `family` | SVG strings | Used by |
| --- | --- | --- | --- |
| Default | `default` | `@videojs/html/icons` or `@videojs/html/icons/default` | The default skins, such as [`<video-skin>`](https://videojs.org/docs/framework/html/reference/components/video-skin) |
| Neutral | `neutral` | `@videojs/html/icons/neutral` | The neutral skins, such as [`<video-neutral-skin>`](https://videojs.org/docs/framework/html/reference/components/video-neutral-skin) |
| Compat | `compat` | `@videojs/html/icons/compat` | The compat skins, such as [`<video-compat-skin>`](https://videojs.org/docs/framework/html/reference/components/video-compat-skin) |

## Available icons

| Name | Export |
| --- | --- |
| `airplay-enter` | `airPlayEnterIcon` |
| `airplay-exit` | `airPlayExitIcon` |
| `captions-off` | `captionsOffIcon` |
| `captions-on` | `captionsOnIcon` |
| `cast-enter` | `castEnterIcon` |
| `cast-exit` | `castExitIcon` |
| `check` | `checkIcon` |
| `chevron` | `chevronIcon` |
| `fullscreen-enter` | `fullscreenEnterIcon` |
| `fullscreen-exit` | `fullscreenExitIcon` |
| `gear` | `gearIcon` |
| `pause` | `pauseIcon` |
| `pip-enter` | `pipEnterIcon` |
| `pip-exit` | `pipExitIcon` |
| `play` | `playIcon` |
| `quality` | `qualityIcon` |
| `restart` | `restartIcon` |
| `seek` | `seekIcon` |
| `speech` | `speechIcon` |
| `speed` | `speedIcon` |
| `spinner` | `spinnerIcon` |
| `switches` | `switchesIcon` |
| `volume-high` | `volumeHighIcon` |
| `volume-low` | `volumeLowIcon` |
| `volume-off` | `volumeOffIcon` |

## Element

`<media-icon>` renders a registered icon as its child `<svg>`, in the light DOM. It renders nothing when the name is not registered in the family.

| Attribute | Default | Description |
| --- | --- | --- |
| `name` | — | Icon name from the [available icons](https://videojs.org/docs/framework/html/reference/components/icons#available-icons), such as `play` |
| `family` | `default` | Icon set to read from, such as `neutral` |

```html
<media-play-button>
  <media-icon class="play-icon" name="play"></media-icon>
  <media-icon class="pause-icon" name="pause" family="neutral"></media-icon>
</media-play-button>
```

Each module below defines `<media-icon>` if it is not already defined:

| Module | Registers |
| --- | --- |
| `@videojs/html/icons/element` | Every set, loading each one the first time a `<media-icon>` asks for its family |
| `@videojs/html/icons/element/default` | The default set, up front |
| `@videojs/html/icons/element/neutral` | The neutral set, up front |
| `@videojs/html/icons/element/compat` | The compat set, up front |

## SVG strings

Each icon export from `@videojs/html/icons`, `@videojs/html/icons/default`, `@videojs/html/icons/neutral`, and `@videojs/html/icons/compat` is the icon’s SVG markup as a string; `@videojs/html/icons` also exports [`registerIcons`](https://videojs.org/docs/framework/html/reference/components/icons#registericons). Importing them does not define `<media-icon>`.

```ts
import { playIcon } from "@videojs/html/icons";

button.innerHTML = playIcon;
```

## `registerIcons`

`registerIcons(family, icons)` registers SVG strings under icon names for `<media-icon>` and defines the element if needed. Only the icons you import ship, which is how skin source from the Shadcn registry registers its icons. Registering into an existing family adds to it, and `<media-icon>` elements already in the page update.

```ts
import { pauseIcon, playIcon, registerIcons } from "@videojs/html/icons";

registerIcons("default", { play: playIcon, pause: pauseIcon });
registerIcons("brand", { play: '<svg viewBox="0 0 18 18">…</svg>' });
```

```html
<media-icon name="play"></media-icon>
<media-icon name="play" family="brand"></media-icon>
```

Once a family has registered icons, `<media-icon>` renders only those for it, even when `@videojs/html/icons/element` is also imported. `registerIcons` throws when a different element is already defined as `media-icon` and does not support registration.

## 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
media-icon svg {
  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/html/reference/components/play-button), provide one automatically.