ReferencePlayer

createPlayer

Factory function that creates a typed player element and controller for HTML custom elements

Import

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 already bound to that player, and playerContext as a lower-level escape hatch. Import ContainerElement separately when you need a custom container.

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

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

Play Pause

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

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

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<string, unknown>): 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<VideoPlayerStore>

Creates a typed HTML player class and bound controller.

Parameters

Parameter Type Default Details

config* object —

Parameter	Type	Default	Details
`config*`	`object`	—
Description Player configuration with features. Type { features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }

Description

Player configuration with features.

Type

{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaQualityState>, PlayerFeature<MediaAudioTrackState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaFullscreenState>, PlayerFeature<MediaPictureInPictureState>, PlayerFeature<MediaRemotePlaybackState>, PlayerFeature<MediaControlsState>, PlayerFeature<MediaTextTrackState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }

Return Value

Property	Type	Details
`PlayerElement`	`typeof UIElement & (new (...args: any...`
Description Configured player element class that owns the store and attachment lifecycle. Type `typeof UIElement & (new (...args: any[]) => PlayerElement<VideoPlayerStore>)`
`PlayerController`	`object`
Description Player controller bound to this player's context. Type `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<VideoPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<VideoPlayerStore['state'], Result>): PlayerController<VideoPlayerStore, Result> }`
`playerContext`	`Context<symbol, VideoPlayerStore>`
Description Context that carries the player store to descendant elements.

Audio

createPlayer(config): CreatePlayerResult<AudioPlayerStore>

Creates a typed HTML audio player class and bound controller.

Parameters

Parameter Type Default Details

config* object —

Parameter	Type	Default	Details
`config*`	`object`	—
Description Player configuration with features. Type `{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }`

Description

Player configuration with features.

Type

{ features: [PlayerFeature<MediaPlaybackState>, PlayerFeature<MediaPlaybackRateState>, PlayerFeature<MediaVolumeState>, PlayerFeature<MediaTimeState>, PlayerFeature<MediaSourceState>, PlayerFeature<MediaBufferState>, PlayerFeature<MediaErrorState>, typeof metadataFeature] }

Return Value

Property	Type	Details
`PlayerElement`	`typeof UIElement & (new (...args: any...`
Description Configured player element class that owns the store and attachment lifecycle. Type `typeof UIElement & (new (...args: any[]) => PlayerElement<AudioPlayerStore>)`
`PlayerController`	`object`
Description Player controller bound to this player's context. Type `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<AudioPlayerStore>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<AudioPlayerStore['state'], Result>): PlayerController<AudioPlayerStore, Result> }`
`playerContext`	`Context<symbol, AudioPlayerStore>`
Description Context that carries the player store to descendant elements.

Generic

createPlayer<const Features extends AnyPlayerFeature[]>(config): CreatePlayerResult<PlayerStore<Features>>

Creates a typed HTML player class with custom features.

Parameters

Parameter	Type	Default	Details
`config*`	`{ features: Features }`	—
Description Player configuration with features.

Return Value

Property	Type	Details
`PlayerElement`	`typeof UIElement & (new (...args: any...`
Description Configured player element class that owns the store and attachment lifecycle. Type `typeof UIElement & (new (...args: any[]) => PlayerElement<PlayerStore<Features>>)`
`PlayerController`	`object`
Description Player controller bound to this player's context. Type `{ new (host: ReactiveControllerHost & HTMLElement): PlayerController<PlayerStore<Features>>; new <Result>(host: ReactiveControllerHost & HTMLElement, selector: Selector<PlayerStore<Features>['state'], Result>): PlayerController<PlayerStore<Features>, Result> }`
`playerContext`	`Context<symbol, PlayerStore<Features>>`
Description Context that carries the player store to descendant elements.