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/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>
  );
}

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/react/videoGeneral-purpose video player preset with full playback controls.
@videojs/react/audioAudio-only player preset with playback and volume controls.
@videojs/react/backgroundAmbient background video preset with no user controls.
@videojs/react/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/react/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 React preset exports a named, preconfigured player component and typed usePlayer hook, plus the building blocks needed to extend its features, add its skin source to your project, or swap its media element:

  • Player — A player component named for the preset, such as VideoPlayer, already configured with the preset’s feature bundle.
  • Typed hook — A usePlayer hook whose state and actions match the preset.
  • Feature bundle — An array of features that define the player’s state and actions. For example, the video feature bundle includes playback, volume, time, fullscreen, and more.
  • Skins — Pre-built UIs designed for that feature bundle. For example, a video skin renders fullscreen and PiP controls because the video feature bundle includes those features. An audio skin doesn’t.
  • Media element — A media component suited to the use case. For example, the background video element bakes in autoplay, mute, and loop.

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.

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:

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

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:

<VideoPlayer>
  <VideoSkin>
    <HlsJsVideo src="https://example.com/stream.m3u8" />
  </VideoSkin>
</VideoPlayer>