Skip to content

GuideConcepts

Presets

Pre-packaged player configurations that bundle state management, skins, and media elements for specific use cases.

A preset packages what you need for a specific player use case. It can include special state management, one or more skins for UI, and specific media elements. Instead of assembling these pieces individually, you pick a preset that matches what you’re building.

For example, the @videojs/html/background preset includes a media element with autoplay, mute, and loop built in, a skin with no controls, and just the features needed to power them:

<script type="module">
  import '@videojs/html/background/player';
  import '@videojs/html/background/video';
  import '@videojs/html/background/skin';
</script>

<background-video-player>
  <background-video-skin>
    <background-video src="hero.mp4"></background-video>
  </background-video-skin>
</background-video-player>

Available presets

The default presets are /video and /audio. These cover the baseline controls you’d expect from the HTML <video> and <audio> tags. Beyond the defaults, presets target more specific use cases — the /background preset, for example, needs layout but not controls. Over time we’ll add more: short-form players, podcast players, TV streaming players, and others.

ImportDescriptionDetails
@videojs/html/videoGeneral-purpose video player preset with full playback controls.
@videojs/html/audioAudio-only player preset with playback and volume controls.
@videojs/html/backgroundAmbient background video preset with no user controls.
@videojs/html/live-audioLive audio player preset — audio minus playback rate, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.
@videojs/html/live-videoLive video player preset — video minus playback rate, quality selection, and audio-track selection, plus the live feature, with a skin that swaps the time slider and time displays for a Live button.

What’s in a preset

Each HTML preset provides registration entry points for a preconfigured player element, its skins, and any preset-specific media element, plus the feature bundle needed to compose your own player. For example, @videojs/html/video/player registers <video-player>, while @videojs/html/video/skin registers <video-skin>.

These parts aren’t equally tied together. Skins depend tightly on their feature bundle — a skin expects specific features to exist. Media elements are more interchangeable — you can swap in an HLS or DASH provider without changing your skin or features.

HTML preset roots are side-effect-free modules for importing the configured classes, typed controller, and feature bundle:

import {
  PlayerController,
  VideoPlayerElement,
  VideoSkinElement,
  videoFeatures,
} from '@videojs/html/video';

Registration is explicit, so importing a value never changes the custom element registry. Registration entry points are side-effect-only; import classes, controllers, and types from the preset root:

import '@videojs/html/video/player'; // <video-player> only
import '@videojs/html/video/skin';   // <video-skin> + container + video UI
// Import '@videojs/html/video/minimal-skin' instead for the minimal skin.

A complete player imports video/player and one skin. Each skin registration includes its container and UI dependencies but does not register the player.

Customizing a preset

You can customize a preset in three ways: extend its feature bundle, add its skin source to your project, or swap its media element.

Extend the feature bundle

Add features to a preset’s feature bundle to enable new functionality. For example, adding playback controls to a background video:

<script type="module">
  import { createPlayer, playbackFeature } from '@videojs/html';
  import { backgroundFeatures } from '@videojs/html/background';
  import '@videojs/html/background/video';
  import '@videojs/html/ui/container';
  import '@videojs/html/ui/play-button';

  const { PlayerElement: MyPlayer } = createPlayer({
    features: [...backgroundFeatures, playbackFeature],
  });

  customElements.define('my-player', MyPlayer);
</script>

<my-player>
  <media-container>
    <background-video src="hero.mp4"></background-video>
    <media-play-button>Play / Pause</media-play-button>
  </media-container>
</my-player>

Skin source

If a preset’s skin is close but not quite right, add its source to your project and customize its components and styles.

Swap the media element

A preset’s default media element is just the starting point. You can replace it with any compatible media provider. For example, using an HLS source with the video preset:

<video-player>
  <video-skin>
    <hlsjs-video src="https://example.com/stream.m3u8"></hlsjs-video>
  </video-skin>
</video-player>