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/react/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:

import { BackgroundVideo, BackgroundVideoPlayer, BackgroundVideoSkin } from '@videojs/react/background';
import '@videojs/react/background/skin.css';

function Hero() {
  return (
    <BackgroundVideoPlayer>
      <BackgroundVideoSkin>
        <BackgroundVideo src="hero.mp4" />
      </BackgroundVideoSkin>
    </BackgroundVideoPlayer>
  );
}

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.

Import	Description	Details
`@videojs/html/video`	General-purpose video player preset with full playback controls.
Feature bundle `videoFeatures` Features playback, playbackRate, quality, audioTrack, volume, time, source, buffer, fullscreen, pip, remotePlayback, controls, textTrack, error, metadata Skins `<video-minimal-skin>`, `<video-skin>` Default media element `<video>`
`@videojs/html/audio`	Audio-only player preset with playback and volume controls.
Feature bundle `audioFeatures` Features playback, playbackRate, volume, time, source, buffer, error, metadata Skins `<audio-minimal-skin>`, `<audio-skin>` Default media element `<audio>`
`@videojs/html/background`	Ambient background video preset with no user controls.
Feature bundle `backgroundFeatures` Features – Skins `<background-video-skin>` Default media element `<background-video>`
`@videojs/html/live-audio`	Live 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.
Feature bundle `liveAudioFeatures` Features playback, volume, time, source, buffer, error, live, metadata Skins `<live-audio-minimal-skin>`, `<live-audio-skin>` Default media element `<audio>`
`@videojs/html/live-video`	Live 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.
Feature bundle `liveVideoFeatures` Features playback, volume, time, source, buffer, fullscreen, pip, remotePlayback, controls, textTrack, error, live, metadata Skins `<live-video-minimal-skin>`, `<live-video-skin>` Default media element `<video>`

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, eject its skin, 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:

import { Container, createPlayer, playbackFeature, PlayButton } from '@videojs/react';
import { backgroundFeatures, BackgroundVideo } from '@videojs/react/background';

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

function Hero() {
  return (
    <Player>
      <Container>
        <BackgroundVideo src="hero.mp4" />
        <PlayButton />
      </Container>
    </Player>
  );
}

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

Eject the skin

If a preset’s skin is close but not quite right, eject it 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>