Skip to main content
Beta@videojs/react is close to stable. Experimental adoption in real projects is welcome.
@videojs/react is a comprehensive library for building media players in React applications. It provides a complete set of components, hooks, and utilities for creating feature-rich, accessible video and audio players.

Installation

npm install @videojs/react
Peer dependency: React >=16.8.0 must be installed in your project.

Exports

Entry pointDescription
.Main entry — core exports, React primitives, UI components, hooks, and utilities
./videoVideo player preset with default skin and layout
./audioAudio player preset
./backgroundBackground player preset
./media/*Individual media component modules

Quick start

Use a preset for the fastest path to a working player:
import { Player, PlayerSkin } from '@videojs/react/video';
import '@videojs/react/video/skin.css';

export function App() {
  return (
    <Player src="https://example.com/video.m3u8">
      <PlayerSkin />
    </Player>
  );
}

Key API

Player setup

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

const { Provider } = createPlayer({
  features: [/* feature modules */],
});

function App() {
  return (
    <Provider src="https://example.com/video.m3u8">
      <Container>
        {/* player UI */}
      </Container>
    </Provider>
  );
}

Hooks

import { usePlayer, useMedia, usePlayerContext } from '@videojs/react';

// Access the player controller
const player = usePlayer();

// Access media state
const media = useMedia();

// Access the full player context
const context = usePlayerContext();

UI components

All standard player controls are available as composable React components:
import {
  Controls,
  PlayButton,
  MuteButton,
  VolumeSlider,
  TimeSlider,
  Time,
  FullscreenButton,
  PiPButton,
  CaptionsButton,
  PlaybackRateButton,
  SeekButton,
  BufferingIndicator,
  Poster,
  Thumbnail,
  Tooltip,
  Popover,
  AlertDialog,
} from '@videojs/react';

State management

import { createSelector, useSelector, useStore, shallowEqual } from '@videojs/react';

const selectVolume = createSelector((state) => state.volume);

function VolumeDisplay() {
  const volume = useSelector(selectVolume);
  return <span>{Math.round(volume * 100)}%</span>;
}

Utilities

import { mergeProps, renderElement, useButton, useSlider } from '@videojs/react';

// Merge multiple prop objects (useful for compound components)
const merged = mergeProps(defaultProps, userProps);

// Build accessible button behavior
const buttonProps = useButton({ onClick: handleClick });

// Build accessible slider behavior
const sliderProps = useSlider({ min: 0, max: 100, value: 50 });

Exports reference

Player API

ExportTypeDescription
createPlayerFunctionCreates a player instance with a React Provider component
ContainerComponentRoot container that connects child components to the player
usePlayerHookReturns the player controller
usePlayerContextHookReturns the full player context value
useMediaHookReturns current media element state
useMediaRegistrationHookRegisters a media element with the player

UI components

ExportDescription
PlayButtonPlay/pause toggle
MuteButtonMute/unmute toggle
FullscreenButtonFullscreen toggle
PiPButtonPicture-in-picture toggle
SeekButtonSeek forward/backward by a fixed interval
CaptionsButtonCaptions/subtitles toggle
PlaybackRateButtonPlayback speed selector
TimeSliderScrubber/seek bar
VolumeSliderVolume control slider
SliderGeneric accessible slider primitive
TimeCurrent time / duration display
ThumbnailPreview thumbnail
BufferingIndicatorLoading/buffering state indicator
PosterVideo poster image
ControlsLayout container for grouping controls
TooltipAccessible tooltip
PopoverAccessible popover
AlertDialogAccessible alert dialog

Utilities

ExportDescription
mergePropsMerges multiple prop objects, combining event handlers
renderElementRenders a component or render function
useButtonHook returning accessible button props
useSliderHook returning accessible slider props
createSelectorCreates a memoized state selector
shallowEqualShallow equality comparator
useSelectorReact hook for subscribing to store state
useStoreReact hook returning the raw store

Dependencies

PackageRole
@videojs/coreCore player logic and feature definitions
@videojs/storeReactive state management
@videojs/spfStream Processing Framework
@videojs/utilsShared utility functions

@videojs/core

Runtime-agnostic core used by this package.

@videojs/html

Web Components alternative for framework-free environments.

@videojs/store

Reactive state management powering useSelector and useStore.

@videojs/utils

Shared utilities used across the stack.

Build docs developers (and LLMs) love