createPlayer

Factory function that creates a player instance with typed store, mixins, 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, ContainerMixin, and a create store factory.

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

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

// Provider element: owns and publishes the store
class VideoPlayer extends ProviderMixin(MediaElement) {}

// Container element: discovers <video>/<audio> and calls store.attach()
class MediaContainer extends ContainerMixin(MediaElement) {}

customElements.define('video-player', VideoPlayer);
customElements.define('media-container', MediaContainer);

Composition patterns

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

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

class VideoPlayer extends ProviderMixin(MediaElement) {}
class MediaContainer extends ContainerMixin(MediaElement) {}

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

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

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

When using the built-in defined elements (@videojs/html/video/player, etc.), media-container is expected as the first child and UI should live inside it.

Examples

Basic Usage

<demo-video-player class="html-create-player-basic">
    <media-container>
        <video
            src="https://stream.mux.com/lhnU49l1VGi3zrTAZhDm9LUUxSjpaPW9BL4jY25Kwo4/highest.mp4"
            autoplay
            muted
            playsinline
        ></video>
        <demo-play-toggle class="html-create-player-basic__button">
            <span class="show-when-paused">Play</span>
            <span class="show-when-playing">Pause</span>
        </demo-play-toggle>
    </media-container>
</demo-video-player>

.html-create-player-basic {
  position: relative;
}

.html-create-player-basic video {
  width: 100%;
}

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

.html-create-player-basic__button .show-when-paused {
  display: none;
}

.html-create-player-basic__button .show-when-playing {
  display: none;
}

.html-create-player-basic__button[data-paused] .show-when-paused {
  display: inline;
}

.html-create-player-basic__button:not([data-paused]) .show-when-playing {
  display: inline;
}

import {
  applyElementProps,
  applyStateDataAttrs,
  createButton,
  createPlayer,
  MediaElement,
  selectPlayback,
} from '@videojs/html';
import { videoFeatures } from '@videojs/html/video';
import '@videojs/html/media/container';

const { ProviderMixin, PlayerController, 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, this.#disconnect.signal);
  }

  override disconnectedCallback(): void {
    super.disconnectedCallback();
    this.#disconnect?.abort();
    this.#disconnect = null;
  }

  protected override update(): void {
    super.update();
    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 typed store, mixins, and controller.

Parameters

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

Return Value

Property	Type
`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.
`ContainerMixin`	`ContainerMixin<Store>`
Description Mixin that consumes player context and auto-attaches media elements.

Audio

Creates a player factory for audio media.

Parameters

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

Return Value

Property	Type
`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.
`ContainerMixin`	`ContainerMixin<Store>`
Description Mixin that consumes player context and auto-attaches media elements.

Generic

Creates a player factory with custom features.

Parameters

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

Return Value

Property	Type
`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.
`ContainerMixin`	`ContainerMixin<Store>`
Description Mixin that consumes player context and auto-attaches media elements.