# Video.js v10 — HTML API (complete)
> Every HTML API page in one file (about 24k tokens). Index with descriptions: https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/llms.txt
---
# createPlayer
Factory function that creates a typed player element and controller for HTML custom elements
## Import
```ts
import { createPlayer } from "@videojs/html";
import { videoFeatures } from "@videojs/html/video";
```
`createPlayer` is the entry point for custom HTML player compositions. It accepts a `features` array and returns the configured `PlayerElement`, a [`PlayerController`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/player-controller) already bound to that player, and `playerContext` as a lower-level escape hatch. Import `ContainerElement` separately when you need a custom container.
**player.ts**
```ts
import { createPlayer, UIElement, selectPlayback } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
features: videoFeatures,
});
customElements.define('video-player', VideoPlayerElement);
// Control element with selector
class PlayButton extends UIElement {
#playback = new PlayerController(this, selectPlayback);
}
```
`PlayerElement` and `PlayerController` are scoped to the created player’s feature set. The element owns its store and attachment lifecycle; the configured controller does not need a context argument. `ContainerElement` consumes the shared player context, so the same class works with any created player.
Use split elements (recommended for reusable skins/layouts):
**player.ts**
```ts
import { ContainerElement, createPlayer } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
const { PlayerElement: PlayerRoot } = createPlayer({ features: videoFeatures });
class PlayerRegion extends ContainerElement {}
```
## Examples
### Basic Usage
**index.html**
```html
PlayPause
```
**index.css**
```css
.demo-video-player media-container {
position: relative;
}
.demo-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[data-paused] .paused {
display: inline;
}
.media-play-button:not([data-paused]) .playing {
display: inline;
}
```
**index.ts**
```ts
import {
applyElementProps,
applyStateDataAttrs,
createButton,
createPlayer,
selectPlayback,
UIElement,
} from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/ui/container';
const { PlayerElement: VideoPlayerElement, PlayerController } = createPlayer({
features: videoFeatures,
});
class PlayToggle extends UIElement {
static readonly tagName = 'demo-play-toggle';
readonly #player = new PlayerController(this, selectPlayback);
#disconnect: AbortController | null = null;
override connectedCallback(): void {
super.connectedCallback();
this.#disconnect = new AbortController();
const buttonProps = createButton({
onActivate: () => {
const state = this.#player.value;
if (!state) return;
state.paused ? state.play() : state.pause();
},
isDisabled: () => !this.#player.value,
});
applyElementProps(this, buttonProps, { signal: this.#disconnect.signal });
}
override disconnectedCallback(): void {
super.disconnectedCallback();
this.#disconnect?.abort();
this.#disconnect = null;
}
protected override update(changed: Map): void {
super.update(changed);
const state = this.#player.value;
if (!state) return;
applyStateDataAttrs(this, state, { paused: 'data-paused', ended: 'data-ended' });
}
}
customElements.define('demo-video-player', VideoPlayerElement);
customElements.define(PlayToggle.tagName, PlayToggle);
```
## API Reference
### Video
`createPlayer(config): CreatePlayerResult`
Creates a typed HTML player class and bound controller.
#### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: [PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, typeof metadataFeature] }` | — | Player configuration with features. |
#### Return Value
| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController; new (host: ReactiveControllerHost & HTMLElement, selector: Selector): PlayerController }` | Player controller bound to this player's context. |
| `playerContext` | `Context` | Context that carries the player store to descendant elements. |
### Audio
`createPlayer(config): CreatePlayerResult`
Creates a typed HTML audio player class and bound controller.
#### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: [PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, PlayerFeature, typeof metadataFeature] }` | — | Player configuration with features. |
#### Return Value
| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController; new (host: ReactiveControllerHost & HTMLElement, selector: Selector): PlayerController }` | Player controller bound to this player's context. |
| `playerContext` | `Context` | Context that carries the player store to descendant elements. |
### Generic
`createPlayer(config): CreatePlayerResult>`
Creates a typed HTML player class with custom features.
#### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `config` (required) | `{ features: Features }` | — | Player configuration with features. |
#### Return Value
| Property | Type | Description |
| --- | --- | --- |
| `PlayerElement` | `typeof UIElement & (new (...args: any[]) => PlayerElement>)` | Configured player element class that owns the store and attachment lifecycle. |
| `PlayerController` | `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController>; new (host: ReactiveControllerHost & HTMLElement, selector: Selector['state'], Result>): PlayerController, Result> }` | Player controller bound to this player's context. |
| `playerContext` | `Context>` | Context that carries the player store to descendant elements. |
---
# PlayerController
Reactive controller for accessing player store state in HTML custom elements
## Import
```ts
import { PlayerController } from "@videojs/html/video";
```
`PlayerController` is a reactive controller that consumes the player store from `playerContext`. Without a selector it returns the store instance directly (no subscription — use this for actions). With a selector it returns the selected value and subscribes to changes, triggering a host update on shallow-equal change. Access the current value via `.value`, which returns `undefined` until connected to a player.
The controller exported by each preset, or returned by [`createPlayer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/html-create-player), is already bound to that player’s context, so pass only the host and optional selector. The lower-level `PlayerController` exported from `@videojs/html` accepts the context as its second argument; its constructor signatures are documented below.
```ts
import { UIElement, selectPlayback } from '@videojs/html';
import { PlayerController } from '@videojs/html/video';
class PlayButtonElement extends UIElement {
readonly #playback = new PlayerController(this, selectPlayback);
}
```
## Examples
### Basic Usage
**index.html**
```html
Paused: Yes | Time: 0.0s | Volume: 100%
```
**index.css**
```css
.demo-ctrl-player media-container {
position: relative;
}
.demo-ctrl-player media-container video {
width: 100%;
}
.panel {
display: flex;
gap: 16px;
align-items: center;
padding: 12px;
background: rgba(0, 0, 0, 0.05);
border-top: 1px solid rgba(0, 0, 0, 0.1);
}
.actions {
display: flex;
gap: 6px;
}
.actions button {
padding: 4px 12px;
font-size: 0.8125rem;
color: #111827;
cursor: pointer;
background: white;
border: 1px solid #ccc;
border-radius: 6px;
}
.state {
font-size: 0.8125rem;
font-variant-numeric: tabular-nums;
color: #374151;
}
```
**index.ts**
```ts
import {
applyElementProps,
createButton,
createPlayer,
selectPlayback,
selectTime,
selectVolume,
UIElement,
} from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/ui/container';
const { PlayerElement: DemoPlayerElement, PlayerController } = createPlayer({
features: videoFeatures,
});
class PlayerActions extends UIElement {
static readonly tagName = 'demo-ctrl-actions';
readonly #player = new PlayerController(this);
#disconnect: AbortController | null = null;
override connectedCallback(): void {
super.connectedCallback();
this.#disconnect = new AbortController();
const signal = this.#disconnect.signal;
const playBtn = this.querySelector('.play')!;
const pauseBtn = this.querySelector('.pause')!;
const volumeBtn = this.querySelector('.volume')!;
const bind = (el: HTMLElement, action: () => void) => {
const props = createButton({ onActivate: action, isDisabled: () => !this.#player.value });
applyElementProps(el, props, { signal });
};
bind(playBtn, () => this.#player.value?.play());
bind(pauseBtn, () => this.#player.value?.pause());
bind(volumeBtn, () => this.#player.value?.setVolume(0.5));
}
override disconnectedCallback(): void {
super.disconnectedCallback();
this.#disconnect?.abort();
this.#disconnect = null;
}
}
class PlayerState extends UIElement {
static readonly tagName = 'demo-ctrl-state';
readonly #playback = new PlayerController(this, selectPlayback);
readonly #time = new PlayerController(this, selectTime);
readonly #volume = new PlayerController(this, selectVolume);
protected override update(changed: Map): void {
super.update(changed);
const playback = this.#playback.value;
const time = this.#time.value;
const volume = this.#volume.value;
if (!playback) return;
const el = this.querySelector('.text');
if (el) {
el.textContent = `Paused: ${playback.paused ? 'Yes' : 'No'} | Time: ${(time?.currentTime ?? 0).toFixed(1)}s | Volume: ${Math.round((volume?.volume ?? 0) * 100)}%`;
}
}
}
customElements.define('demo-ctrl-player', DemoPlayerElement);
customElements.define(PlayerActions.tagName, PlayerActions);
customElements.define(PlayerState.tagName, PlayerState);
```
## API Reference
### Without Selector
`new PlayerController(host, context)`
#### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise } & HTMLElement` | — | The host element that owns this controller. |
| `context` (required) | `Context` | — | Player context to resolve the store from. |
#### Return Value
| Property | Type |
| --- | --- |
| `value` | `Result \| undefined` |
| `displayName` | `string \| undefined` |
### With Selector
`new PlayerController(host, context, selector)`
#### Parameters
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `host` (required) | `{ addController(controller: ReactiveController): void; removeController(controller: ReactiveController): void; requestUpdate(): void; updateComplete: Promise } & HTMLElement` | — | The host element that owns this controller. |
| `context` (required) | `Context` | — | Player context to resolve the store from. |
| `selector` (required) | `{ (state: Store['state']): Result; displayName?: string }` | — | Derives a value from the player store state. |
#### Return Value
| Property | Type |
| --- | --- |
| `value` | `Result \| undefined` |
| `displayName` | `string \| undefined` |
---
# createSelector
Create a type-safe selector for a store slice's state
## Import
```ts
import { createSelector } from "@videojs/store";
```
`createSelector` is also re-exported from `@videojs/react` and `@videojs/html`.
`createSelector` creates a type-safe selector function for a given slice. The returned selector extracts that slice’s state from the full store state, or returns `undefined` if the slice is not configured.
The built-in selectors ([`selectPlayback`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/feature-playback), [`selectBuffer`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/feature-buffer), etc.) are all created with `createSelector`. Use it to create selectors for custom slices.
**my-custom-selector.ts**
```ts
import { createSelector } from '@videojs/store';
import { myCustomSlice } from './my-custom-slice';
const selectCustom = createSelector(myCustomSlice);
// Use with usePlayer (React) or PlayerController (HTML)
const state = selectCustom(store.state);
```
Pass selectors to [`PlayerController`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/player-controller) or [`StoreController`](https://deploy-preview-2971--vjs10-site.netlify.app/docs/framework/html/reference/api/store-controller) for reactive subscriptions.
## API Reference
`createSelector(slice): Selector