createPlayer

Factory function that creates a player instance with a typed store, provider mixin, and controller for HTML custom elements

createPlayer is the entry point for setting up a Video.js player with HTML custom elements. It accepts a configuration object with a features array and returns a typed PlayerController, context, ProviderMixin, and a create store factory. Import ContainerMixin separately from the main package when composing a container.

import { ContainerMixin, createPlayer, MediaElement, selectPlayback } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

const { ProviderMixin, PlayerController, context } = createPlayer({
  features: videoFeatures,
});

// Provider element: owns the store, provides context to descendants
class VideoPlayer extends ProviderMixin(MediaElement) {}
customElements.define('video-player', VideoPlayer);

// Control element with selector
class PlayButton extends MediaElement {
  #playback = new PlayerController(this, context, selectPlayback);
}

PlayerController and ProviderMixin are scoped to the created player’s feature set. The root ContainerMixin consumes the shared player context, so the same import works with any created player.

Use split elements (recommended for reusable skins/layouts):

import { ContainerMixin, createPlayer, MediaElement } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

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

class PlayerRoot extends ProviderMixin(MediaElement) {}
class PlayerRegion extends ContainerMixin(MediaElement) {}

Use a single composed element when the same element should both own the store and attach media:

import { ContainerMixin, createPlayer, MediaElement } from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';

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

class ComposedPlayer extends ProviderMixin(ContainerMixin(MediaElement)) {}

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 {
  position: relative;
}

.demo-video-player 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,
  MediaElement,
  PlayerController,
  selectPlayback,
} from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/media/container';

const { ProviderMixin, context } = createPlayer({
  features: videoFeatures,
});

class VideoPlayer extends ProviderMixin(MediaElement) {
  static readonly tagName = 'demo-video-player';
}

class PlayToggle extends MediaElement {
  static readonly tagName = 'demo-play-toggle';

  readonly #player = new PlayerController(this, context, 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(VideoPlayer.tagName, VideoPlayer);
customElements.define(PlayToggle.tagName, PlayToggle);

API Reference

Video

Creates a player factory with a typed store, provider mixin, and controller.

Parameters

Parameter	Type	Default	Details
`config*`	`CreatePlayerConfig<VideoFeatures>`	`—`
Description Player configuration with features.

Return Value

Property	Type	Details
`context`	`PlayerContext<Store>`
Description Context for consuming player in controllers.
`create`	`function`
Description Creates a store instance for imperative access. Type `() => Store`
`PlayerController`	`PlayerController.Constructor<Store>`
Description Player controller bound to this player's context.
`ProviderMixin`	`ProviderMixin<Store>`
Description Mixin that provides player context to descendants.

Audio

Creates a player factory for audio media.

Parameters

Parameter	Type	Default	Details
`config*`	`CreatePlayerConfig<AudioFeatures>`	`—`
Description Player configuration with features.

Return Value

Property	Type	Details
`context`	`PlayerContext<Store>`
Description Context for consuming player in controllers.
`create`	`function`
Description Creates a store instance for imperative access. Type `() => Store`
`PlayerController`	`PlayerController.Constructor<Store>`
Description Player controller bound to this player's context.
`ProviderMixin`	`ProviderMixin<Store>`
Description Mixin that provides player context to descendants.

Generic

Creates a player factory with custom features.

Parameters

Parameter	Type	Default	Details
`config*`	`CreatePlayerConfig<Features>`	`—`
Description Player configuration with features.

Return Value

Property	Type	Details
`context`	`PlayerContext<Store>`
Description Context for consuming player in controllers.
`create`	`function`
Description Creates a store instance for imperative access. Type `() => Store`
`PlayerController`	`PlayerController.Constructor<Store>`
Description Player controller bound to this player's context.
`ProviderMixin`	`ProviderMixin<Store>`
Description Mixin that provides player context to descendants.