Features

Features are bundles of state and behavior that configure your player. Each feature adds specific capabilities—playback controls, volume management, fullscreen support, and more.

Features define what the player can do, what state exists, and how that state stays in sync with the underlying media element or player environment. Features are not UI. Buttons, menus, sliders, and skins are separate—they simply consume feature state and invoke feature requests.

You can think of features as the behavioral and stateful core of the player, independent of how it looks.

Note: If you’re familiar with other state management libraries like Redux or Zustand, features are conceptually similar to “slices”—self-contained modules that manage a specific piece of state and logic.

Mental Model

The player is composed of four layers:

Media element   ← native playback engine
Environment     ← container, input, layout, persistence
Features        ← state + behavior (this document)
UI              ← buttons, menus, skins

• Features observe the media element and the environment.
• Features expose state and requests.
• UI reads feature state and calls requests.
• UI never talks directly to the media element.

This separation lets you change UI freely without re-implementing playback logic, and compose players by mixing and matching features.

Two Tiers of Features

All features fall into one of two conceptual tiers. This distinction is about scope, not about separate stores.

Media Features

Describe playback and media behavior. They primarily observe and control the media element.

Examples:

• playback
• time
• volume
• captions
• fullscreen
• pictureInPicture
• live
• quality
• audioTracks

Environment Features

Describe how the player behaves as an interactive application. They primarily observe and control the player container and user input.

Examples:

• layout
• idle
• hotkeys
• gestures
• i18n
• preferences
• casting / airplay

Both tiers are configured and consumed the same way.

Feature Lifecycle

Every feature participates in the same lifecycle:

1. Initialization

   • Initial state is created
   • Defaults and policies are applied
   • Preferences may be restored

2. Subscription

   • The feature listens to relevant events (media, container, input, timers)

3. Snapshot updates

   • When something changes, the feature updates its state

4. Requests

   • The feature exposes commands that mutate behavior (e.g. play, seek, toggleFullscreen)

This lifecycle is what allows features to stay deterministic, debuggable, and UI-agnostic.

Feature Bundles

Feature bundles are curated collections of features for common scenarios:

Using Features

import { createPlayer, features } from '@videojs/react';
import { VideoSkin } from '@videojs/react/skin/video';
import '@videojs/react/skin/video.css';

const { Provider } = createPlayer({
  features: features.video(),
});

<Provider>
  <VideoSkin>
    <video src="video.mp4" />
  </VideoSkin>
</Provider>

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

Combining Features

Spread a bundle and add more features:

import { createPlayer, features } from '@videojs/react';

const { Provider } = createPlayer({
  features: [
    ...features.video(),
    features.gestures,
  ],
});

import { createPlayer, features } from '@videojs/html';

const { Player } = createPlayer({
  features: [
    ...features.video(),
    features.gestures,
  ],
});

Player.define('gesture-video-player');

Configuring Features

Pass options to configure individual features:

const { Provider } = createPlayer({
  features: features.video({
    playback: {
      autoplay: false,
    },
    idle: {
      autohideSeconds: 2,
    },
    hotkeys: {
      seekForwardSeconds: 15,
      seekBackwardSeconds: 5,
    },
  }),
});

Without a Bundle

You can always configure features directly:

const { Provider } = createPlayer({
  features: [
    features.playback({ autoplay: false }),
    features.time({ defaultDuration: 120 }),
    features.volume(),
    features.fullscreen(),
    features.idle({ autohideSeconds: 2 }),
  ],
});

Media Features Reference

playback

Controls core playback behavior and exposes play/pause state and requests.

What it does:

• Tracks paused / playing / ended
• Issues play() and pause() requests
• Applies startup playback policy

Options:

playbackFeature({
  autoplay: 'muted',
  preload: 'metadata',
});

time

Tracks current playback time, duration, and seeking.

What it does:

• Tracks currentTime and duration
• Exposes seek requests
• Supports optimistic duration before metadata loads

Options:

volume

Tracks volume and mute state.

Options:

captions

Manages text tracks and subtitle state.

Options:

fullscreen

Manages fullscreen state.

Options:

pictureInPicture

Controls Picture-in-Picture state.

No options.

live

Handles live vs on-demand behavior.

Options:

quality

Manages rendition and quality selection.

Options:

Environment Features Reference

Environment features attach to the player container and describe layout, interaction, and application behavior.

layout

Controls responsive and structural behavior.

Options:

idle

Tracks user activity and idle state.

Options:

hotkeys

Handles keyboard shortcuts.

Options:

gestures

Controls pointer-based gestures.

Options:

i18n

Provides language selection and translation.

Options:

preferences

Handles persistence of user preferences.

Options:

casting / airplay

Controls external playback targets.

No options.

Summary

• Features define capabilities, not UI.
• Media and environment features share the same model.
• Options configure policy and defaults, not reactive state.
• Presets are composable helpers, not abstractions you’re locked into.
• UI reads feature state and issues requests—nothing more.

See Also

• Architecture — How features fit in the three-pillar model
• Skins — Packaged player designs
• UI Components — How UI consumes feature state