React AV

Headless, hooks-based building blocks for audio and video in React.

Documentation · Live demos · Issues

---

React AV gives you the state, behaviour, and accessibility of a full media player with no markup or styles imposed. You compose the primitives you need and style them however you like. It works with plain HTML5 media, HLS, and DASH, and ships with its own WebVTT engine and a subtitle timeline editor.

Features

• Headless. Every component is unstyled and accepts the props of the element it renders.
• Hooks for everything. Read and control playback, volume, buffering, fullscreen, and more from any component.
• Bring your own source. HTML5 <video>/<audio> out of the box, with HLS and DASH through Shaka Player.
• WebVTT built in. A standalone W3C WebVTT parser and renderer for captions, chapters, and storyboards.
• Timeline editor. Composable components for building subtitle and media editing interfaces.
• Cross-browser. Fullscreen and picture-in-picture are normalised across browsers.
• Typed. Written in TypeScript with declarations included.

Quick start

npm i @react-av/core @react-av/controls

import * as Media from "@react-av/core";
import { PlayPause, Mute, Timestamp, Fullscreen } from "@react-av/controls";

export function Player() {
  return (
    <Media.Root>
      <Media.Container>
        <Media.Video src="/video.mp4" />
      </Media.Container>
      <Media.Viewport>
        <PlayPause />
        <Timestamp type="remaining" />
        <Mute />
        <Fullscreen />
      </Media.Viewport>
    </Media.Root>
  );
}

Every piece of media state is a hook, so building your own controls takes a few lines:

function PlayButton() {
  const [playing, setPlaying] = Media.useMediaPlaying();
  return <button onClick={() => setPlaying(!playing)}>{playing ? "Pause" : "Play"}</button>;
}

Packages

Package	Description
@react-av/core	Media root, video/audio elements, viewport, and state hooks.
@react-av/controls	Play/pause, mute, loop, fullscreen, picture-in-picture, and timestamp controls.
@react-av/sliders	Seek and volume sliders built on Radix UI.
@react-av/vtt-core	Standalone W3C WebVTT parser and renderer.
@react-av/vtt	WebVTT tracks, cues, and caption overlays for React AV.
@react-av/vtt-controls	Storyboard thumbnail previews from WebVTT tracks.
@react-av/shaka	HLS and DASH playback powered by Shaka Player.
@react-av/editor	Timeline editor components for subtitles and media.

Every package except @react-av/vtt-core has react and react-dom as peer dependencies.

Development

This is a pnpm workspace managed with Turborepo.

pnpm install
pnpm build        # build all packages and the docs site
pnpm dev          # watch packages and run the docs site locally
pnpm test         # run the test suite with Vitest

The browser tests in e2e play a real video through the package sources in headless Chromium and WebKit, so no build is needed first. Install the browsers once with pnpm exec playwright install chromium webkit (on Linux, add --with-deps for the system libraries and media codecs). Run only the browser tests with pnpm test --project e2e. Add one e2e/<feature>.test.tsx per feature: use renderPlayer from e2e/player.tsx when its controls cover the flow, otherwise render your own player in the test file, wrapped in StrictMode, with the clip from e2e/fixtures/clip.webm.

The documentation and demo site lives in apps/docs. Releases are versioned with Changesets: run pnpm changes to describe your change before opening a pull request.

Contributing

Issues and pull requests are welcome. For larger changes, please open an issue first so we can agree on the approach.

License

MIT © Daniel Wykerd

Releases

Pull requests run the CI workflow to build the packages and test playback in Chromium and WebKit. The release workflow reuses those checks and waits for them to pass before updating the Version packages PR or publishing its merged versions on master. Enable GitHub Actions to create pull requests in the repository settings. Each public package needs an npm trusted publisher for owner Wykerd, repository react-av, workflow release.yml, with direct publishing allowed. No npm token is needed.

For a manual release, use Node 24, npm 11.5.1 or later, and the pinned pnpm version. Run pnpm version-packages, review and commit the versions, then run pnpm build && pnpm test && pnpm release with your npm login. Merge the version-drift fix before the first release.