React Video Player: Top Libraries, Code Examples, and How to Build One

If you have ever tried to drop a tag into a React component and ship it to production, you already know the gap between “it plays an MP4 on Chrome” and “it streams 4K live to a million viewers.” A real React video player has to handle adaptive bitrate, HLS or DASH manifests, custom controls, mobile autoplay quirks, and analytics — all without breaking React’s render lifecycle.

This guide walks through what a React video player actually is, how the leading libraries compare, and how to build one from scratch with a working code example. You will get a clear picture of when to use a plain HTML5 element, when to reach for react-player, and when to wire up Video.js with HLS support for a streaming app.

What Is a React Video Player?

A React video player is a React component that renders a video element, manages its playback state, and exposes a controlled API so the rest of your app can play, pause, seek, and react to events. It wraps the browser’s HTML5 element (or a third-party engine like Video.js) and integrates it with React’s declarative rendering and hooks.

The core idea is that React owns the props — the source URL, whether it’s playing, the current time, the volume — and the player keeps the underlying media element in sync. You can build one yourself in 30 lines of JSX, or install a battle-tested package that already supports YouTube, Vimeo, HLS, DASH, and dozens of edge cases.

Here is how the main approaches compare at a glance.

How Does a React Video Player Work?

A React video player works by binding a media element to React state and lifecycle hooks. Here is the flow when a user hits the play button:

1. Render the element. React mounts a tag (or a custom component that wraps one) with a src, poster, and controls prop.
2. Attach a ref. A useRef hook gives you direct access to the underlying HTMLMediaElement, which exposes play(), pause(), currentTime, and a stack of media events.
3. Sync state with events. Listeners on onPlay, onPause, onTimeUpdate, and onEnded push the player’s current state back into React state.
4. Decode and render frames. The browser’s media pipeline downloads the file (or streams chunks via Media Source Extensions for HLS/DASH), decodes the video codec, and paints frames to the canvas.
5. Adapt the bitrate. For adaptive streams, the player measures bandwidth, selects a quality level from the manifest, and switches segments mid-playback without buffering.

For static MP4 files, the browser handles steps 4 and 5 natively. For HLS or DASH, you need a JavaScript engine — hls.js, dash.js, or one bundled inside Video.js — that fetches the manifest, downloads .ts or .m4s segments, and feeds them into a MediaSource buffer. Apple Safari plays HLS natively; every other browser needs the polyfill.

If you want a refresher on the underlying protocol, see what is HLS streaming and how adaptive bitrate streaming picks the right quality level for each viewer.

Top React Video Player Libraries Compared

Picking a library comes down to three questions: What sources do you need to support, how custom does the UI need to be, and how big is your bundle budget? Here is a side-by-side comparison of the seven most popular options.

react-player

react-player is the most popular pick when you need one component that plays everything. Pass it a YouTube URL, a Vimeo link, an MP4 file, or an HLS manifest, and it figures out which engine to load. Version 3 adopted a new architecture and brought first-class support for multiple sources and tracks, similar to the native element.

Maintenance moved to Mux, the video API company, which has stabilized release cadence. Trade-offs: the customization surface is small, so deep UI changes mean swapping engines or dropping down to plain .

Video.js with React

Video.js powers more than 700,000 sites and is the workhorse of streaming. The official React wrapper mounts Video.js inside a useEffect, then disposes it on unmount to avoid memory leaks. You get HLS via videojs-http-streaming, quality menus via videojs-contrib-quality-levels, and a plugin ecosystem covering ads, captions, and analytics.

Pick it when you need a custom skin, plugin support, or DRM. Skip it for a tiny bundle — even minified, it is the heaviest option in this list.

Vidstack

Vidstack is the newest entrant and the most opinionated about modern UI. It ships modular components — , , — and lets you tree-shake everything you do not use. Accessibility is solid out of the box, including keyboard shortcuts and screen reader labels.

It supports HLS, DASH, and DRM and pairs well with React Server Components.

mux-player-react

If your videos already live on Mux, this player is plug-and-play. You feed it a playback ID, and it handles HLS streaming, thumbnails, and quality analytics. The same pattern works for any video player API — you point the player at a backend that produces HLS, and the rest is configuration.

video-react

video-react rebuilds Video.js’s component model in idiomatic React. Each control — PlayToggle, ProgressControl, VolumeMenuButton — is its own component. It is a clean fit for HTML5 playback but lags on streaming features.

react-hls-player

A thin wrapper around hls.js that renders a element and configures the HLS engine for you. Ideal for a single-purpose page that has to play one HLS feed without pulling in Video.js.

HTML5 element

Sometimes the right answer is no library at all. The native element handles MP4 and WebM, supports poster, controls, loop, muted, and gives you full control over the markup. You miss HLS on non-Safari browsers, but for pre-rendered MP4 files served from a CDN, it is the lightest possible solution.

How to Build a React Video Player Step by Step

Here is a complete React video player component that handles play, pause, seek, and progress tracking with no external dependencies. Drop it into any React 18+ project.

Step 1: Create the component file

// VideoPlayer.jsx
import { useRef, useState, useEffect } from 'react';

export default function VideoPlayer({ src, poster }) {
  const videoRef = useRef(null);
  const [isPlaying, setIsPlaying] = useState(false);
  const [progress, setProgress] = useState(0);
  const [duration, setDuration] = useState(0);

  useEffect(() => {
    const video = videoRef.current;
    if (!video) return;

    const onTimeUpdate = () => setProgress(video.currentTime);
    const onLoadedMetadata = () => setDuration(video.duration);

    video.addEventListener('timeupdate', onTimeUpdate);
    video.addEventListener('loadedmetadata', onLoadedMetadata);

    return () => {
      video.removeEventListener('timeupdate', onTimeUpdate);
      video.removeEventListener('loadedmetadata', onLoadedMetadata);
    };
  }, []);

  const togglePlay = () => {
    const video = videoRef.current;
    if (isPlaying) {
      video.pause();
    } else {
      video.play();
    }
    setIsPlaying(!isPlaying);
  };

  const handleSeek = (e) => {
    const time = Number(e.target.value);
    videoRef.current.currentTime = time;
    setProgress(time);
  };

  return (
    <div className="player">
      <video
        ref={videoRef}
        src={src}
        poster={poster}
        onEnded={() => setIsPlaying(false)}
      />
      <div className="controls">
        <button onClick={togglePlay}>
          {isPlaying ? 'Pause' : 'Play'}
        </button>
        <input
          type="range"
          min="0"
          max={duration || 0}
          step="0.1"
          value={progress}
          onChange={handleSeek}
        />
        <span>{formatTime(progress)} / {formatTime(duration)}</span>
      </div>
    </div>
  );
}

function formatTime(seconds) {
  const m = Math.floor(seconds / 60);
  const s = Math.floor(seconds % 60).toString().padStart(2, '0');
  return `${m}:${s}`;
}

Step 2: Use it in your app

import VideoPlayer from './VideoPlayer';

function App() {
  return (
    <VideoPlayer
      src="https://example.com/video.mp4"
      poster="https://example.com/thumbnail.jpg"
    />
  );
}

Step 3: Add HLS support with hls.js

For HLS streams (.m3u8 URLs), extend the component with hls.js. Install it first:

npm install hls.js

Then add HLS detection inside the useEffect:

import Hls from 'hls.js';

useEffect(() => {
  const video = videoRef.current;
  if (!video) return;

  if (src.endsWith('.m3u8')) {
    if (video.canPlayType('application/vnd.apple.mpegurl')) {
      video.src = src; // Native HLS in Safari
    } else if (Hls.isSupported()) {
      const hls = new Hls();
      hls.loadSource(src);
      hls.attachMedia(video);
      return () => hls.destroy();
    }
  } else {
    video.src = src;
  }
}, [src]);

Now your player handles MP4 directly, plays HLS natively in Safari, and falls back to hls.js for Chrome, Firefox, and Edge. For a deeper look at the protocol, see how adaptive bit rate renditions are selected on the fly.

Step 4: Add styling

Wrap the controls in CSS to make them look like a real player. Use position: absolute on the controls and position: relative on the container so the controls overlay the video. Show them on hover.

Streaming Protocols Your React Video Player Should Support

A modern react video player rarely plays a static MP4 in production. Most apps need at least one streaming protocol. Here is what each handles.

HLS (HTTP Live Streaming)

Apple’s HLS protocol breaks video into short .ts or fragmented MP4 segments and serves them over HTTP. The client downloads a manifest (.m3u8), checks bandwidth, and picks a rendition. HLS is the dominant protocol for live and on-demand streaming on the open web — see what is HTTP live streaming for the full breakdown.

Your react video player needs hls.js or a library that bundles it (Video.js, Vidstack, react-hls-player) to play HLS outside Safari.

MPEG-DASH

DASH is the open ISO/IEC alternative to HLS. It uses .mpd manifests and works similarly. dash.js is the reference implementation. Pick DASH if your CDN already delivers .mpd files or you are building for non-Apple ecosystems. The DASH video format is more flexible for custom codecs.

CMAF

CMAF is a packaging format that lets a single set of segments serve both HLS and DASH manifests. Backends generate one bucket of .m4s files instead of two. See CMAF vs HLS for the exact differences and when each makes sense.

MP4 progressive download

Plain MP4 over HTTP works for short clips, marketing videos, and anywhere the file is small enough to download in seconds. No manifest, no JavaScript engine — just . The browser handles the rest.

Advanced Features Worth Adding

Once the basic player works, the next questions are usually about quality, security, and analytics. Here is what to add and why.

Adaptive bitrate switching

ABR is what makes video watchable on a mobile network. The player tracks throughput and switches to a lower-bitrate rendition when bandwidth drops. Video.js, Vidstack, and hls.js handle this automatically once you provide a multi-rendition HLS manifest. Tune the video bitrate ladder on the encoder side to match your audience’s devices.

Custom controls and theming

If the default skin clashes with your design system, build your own controls. Keep the native element hidden (controls prop off) and render React buttons that call videoRef.current.play(), pause(), and update currentTime. Library players (Video.js, Vidstack) expose CSS variables and slot APIs for this.

DRM (Widevine, FairPlay, PlayReady)

If you ship paid content, you need DRM. The Encrypted Media Extensions (EME) API in the browser handles license exchange — but the player has to wire it up. Vidstack and Video.js both support DRM via plugins. Read more on DRM for video before picking a license server.

Captions, subtitles, and audio tracks

The HTML5 element handles WebVTT captions natively. For multi-language audio, HLS and DASH manifests can declare alternate audio renditions, and hls.js exposes them through hls.audioTracks.

Analytics and quality of experience

Track playback events — buffering ratio, average bitrate, startup time, dropped frames — to understand viewer experience. The requestVideoFrameCallback API and MediaSource.setLiveSeekableRange give you fine-grained signals. Send them to your analytics backend or a QoE service.

Live latency tuning

For live streams, every second of buffer is a second of delay. Low-latency HLS (LL-HLS) and chunked CMAF can cut video latency from 30 seconds to under 3. Your player has to support partial segments and play at the live edge.

Common Challenges with a React Video Player

These are the issues every team hits at some point. Plan for them up front.

Autoplay blocked on mobile

Browsers block autoplay unless the video is muted. If you need the video to start on page load, set both autoPlay and muted props. iOS Safari also requires playsInline to keep the video from going fullscreen.

<video src={src} autoPlay muted playsInline />

Memory leaks on unmount

If you mount Video.js or hls.js inside useEffect, you must dispose of them in the cleanup function. Forgetting this leaves orphaned media buffers and event listeners.

useEffect(() => {
  const player = videojs(videoRef.current, options);
  return () => player.dispose();
}, []);

React 18 StrictMode double-mount

StrictMode mounts effects twice in development. Library players that initialize on mount can crash on the second run. Guard with a ref check:

const initialized = useRef(false);

useEffect(() => {
  if (initialized.current) return;
  initialized.current = true;
  // initialize player
}, []);

CORS errors with HLS segments

HLS manifests fetch segments via fetch(), which honors CORS. If your CDN does not return Access-Control-Allow-Origin, the player fails silently. Set the header on every segment, including the manifest. Most CDNs for video streaming let you configure this in the dashboard.

Codec incompatibility

Not every browser supports every codec. H.264 is the safe baseline. H.265 (HEVC) only works on Safari. AV1 needs Chrome 70+ or Firefox 67+. If you need cross-browser, transcode to multiple codecs and let the player pick. See what is a video codec for a deeper look at the trade-offs.

Choosing the Right React Video Player

Use this checklist to pick a library:

• Need YouTube, Vimeo, and self-hosted in one component? Use react-player.
• Building a custom-skinned streaming app with plugins? Use Video.js with React.
• Want a modern, accessible, modular API? Use Vidstack.
• Hosting on Mux? Use mux-player-react.
• Just one HLS feed and a small bundle? Use react-hls-player or hls.js directly.
• Static MP4 in a marketing page? Use the native element.

If your video infrastructure is the bottleneck — encoding, storage, delivery, multi-CDN — pair the player with a backend that handles ingestion, transcoding, and HLS output. That is where LiveAPI fits in.

Wiring a React Video Player to a Streaming Backend

A player only renders what your backend hands it. To go from camera or upload to a playable HLS URL, you need an ingest endpoint, a transcoder, storage, and a CDN. Building that pipeline from scratch takes months.

LiveAPI gives you the backend in a single API. You upload an MP4 or push an RTMP or SRT stream to its ingest URL, and it returns an HLS playback URL with multiple bitrate renditions, ready for your react video player. Out of the box you get:

• Live streaming up to 4K via RTMP and SRT ingest
• Instant transcoding so videos play within seconds of upload
• Adaptive bitrate streaming across multiple renditions
• Multiple CDNs (Akamai, Cloudflare, Fastly) for global delivery
• HLS output URLs that drop straight into react-player, Video.js, or Vidstack
• Live-to-VOD recording and webhooks for playback events

A typical wire-up looks like this. Send a video to the API:

const sdk = require('api')('@liveapi/v1.0#5pfjhgkzh9rzt4');
sdk.post('/videos', {
  input_url: 'https://example.com/upload.mp4'
})
.then(res => {
  const hlsUrl = res.data.playback.hls_url;
  // pass hlsUrl to your React video player
});

Then feed the URL into your component:

<VideoPlayer src={hlsUrl} poster={posterUrl} />

If you are building a larger app — auth, billing, recommendations, multiple CDN for live streaming — pair the API with the live streaming API docs and the how to build a video streaming app guide.

For mobile, the same flow works with a react native video example and the react-native-video library.

React Video Player FAQ

Which is the best React video player library in 2026?

It depends on the source mix. react-player is the best choice for apps that play YouTube, Vimeo, and self-hosted videos through one component. Video.js plus the official React wrapper is the best choice for streaming apps that need custom skins, plugins, and HLS or DASH. Vidstack is the best modern alternative if accessibility and bundle size matter.

Is react-player still maintained?

Yes. Maintenance moved to Mux, which released version 3 with a new architecture, and continues to ship fixes. The component remains open source on GitHub.

How do I play HLS in a React app?

Use hls.js to attach an HLS manifest to a element when the browser does not support HLS natively. Safari handles HLS without any library. Chrome, Firefox, and Edge need hls.js, Vidstack, Video.js, or react-hls-player.

How do I build a custom React video player from scratch?

Render a element with a useRef, attach event listeners for timeupdate, play, pause, and loadedmetadata inside a useEffect, and store the playback state in useState. Render your own buttons and progress bar that call videoRef.current.play(), pause(), and set currentTime.

Why does my React video player autoplay break on iOS?

iOS Safari requires three conditions for autoplay: the video must be muted, playsInline, and the source must load from the same origin or with proper CORS. Adding the playsInline attribute also prevents the video from going fullscreen automatically.

Does react-player support DRM?

Not natively. Use Vidstack or Video.js with the videojs-contrib-eme plugin if you need Widevine, FairPlay, or PlayReady support.

How big is Video.js compared to react-player?

Video.js is roughly 80 KB gzipped including its base styles. react-player is about 15 KB gzipped, with extra weight added when an adapter loads (YouTube IFrame API, Vimeo SDK).

Can I use a React video player for live streaming?

Yes. Point any HLS-capable React video player at a live HLS manifest. The player will follow the live edge and update segments as they appear. For sub-second latency, look at WebRTC-based players instead.

How do I add captions to a React video player?

Add a child to the element with kind="subtitles", src pointing at a .vtt file, and a srclang code. Multiple tags let users switch languages.

<video src={src}>
  <track kind="subtitles" src="/captions/en.vtt" srclang="en" label="English" />
  <track kind="subtitles" src="/captions/es.vtt" srclang="es" label="Spanish" />
</video>

Getting Started

A React video player is only as strong as the backend feeding it. If you have the player figured out but need an API that handles ingest, transcoding, storage, and HLS delivery, try LiveAPI free and ship a streaming feature in days instead of months.