Build a custom HLS player in React with hls.js (no wrapper libraries)

TL;DR

We'll build a custom HLS player on top of hls.js 1.6.x and React 19 with no wrapper library. Play/pause, seek, volume, quality readout, buffer state, and proper error recovery. End result is ~150 lines and bends to whatever UI you want.

📦 Code: github.com/USER/react-hls-player-demo (replace before publishing)

This is the "stop installing video.js for the third time" tutorial. The wrapper libraries are doing two things you need (the MSE shim and the error-recovery loop) and a lot of things you don't (a giant control bar, a plugin model, a CSS skin). The MSE shim is hls.js. The error-recovery loop is fifteen lines. Everything else can be your own React.

0. Versions

node 22.x
react 19.x
hls.js 1.6.16   # latest stable as of 2026-04-13

The 1.7 alpha is interesting (interstitial-ads improvements landed in canary on 2026-05-16) but not yet ready for production. Stick with 1.6 unless you're testing the next major.

1. Setup

npm create vite@latest react-hls-player-demo -- --template react-ts
cd react-hls-player-demo
npm install
npm install hls.js

For test streams, the Apple HLS test page has a few public manifests. The bipbop ad-stitched stream is the classic one:

https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_fmp4/master.m3u8

2. The bare minimum: a hook that mounts hls.js

// src/useHls.ts
import { useEffect, useRef } from "react";
import Hls from "hls.js";

export function useHls(src: string) {
  const videoRef = useRef<HTMLVideoElement>(null);

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

    // Safari (and iOS) plays HLS natively. Hand the URL to the browser.
    if (video.canPlayType("application/vnd.apple.mpegurl")) {
      video.src = src;
      return;
    }

    if (!Hls.isSupported()) return;

    const hls = new Hls({
      enableWorker: true,
      lowLatencyMode: true,
      backBufferLength: 30,
    });
    hls.loadSource(src);
    hls.attachMedia(video);

    return () => {
      hls.destroy();
    };
  }, [src]);

  return videoRef;
}

The cleanup matters. React 19's StrictMode mounts every effect twice in development. Without the hls.destroy(), you leak one Hls instance per remount and your dev server's memory usage will climb. Ask me how I know.

// src/App.tsx
import { useHls } from "./useHls";

const SRC = "https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_fmp4/master.m3u8";

export default function App() {
  const videoRef = useHls(SRC);
  return <video ref={videoRef} controls className="w-full max-w-4xl" />;
}

That plays HLS in every modern browser. Eight lines. The wrapper libraries' main value-add, "plays HLS in Chrome", is now done. Everything else is product.

3. Wiring real controls

Drop controls from <video> and write your own. Each control is a small piece of state synced to the element.

// src/Player.tsx
import { useEffect, useRef, useState } from "react";
import Hls from "hls.js";

export function Player({ src }: { src: string }) {
  const videoRef = useRef<HTMLVideoElement>(null);
  const hlsRef = useRef<Hls | null>(null);
  const [playing, setPlaying] = useState(false);
  const [time, setTime] = useState(0);
  const [duration, setDuration] = useState(0);
  const [level, setLevel] = useState<string>("auto");

  useEffect(() => {
    const v = videoRef.current!;
    if (v.canPlayType("application/vnd.apple.mpegurl")) {
      v.src = src;
    } else if (Hls.isSupported()) {
      const hls = new Hls({ enableWorker: true, lowLatencyMode: true });
      hls.loadSource(src);
      hls.attachMedia(v);
      hls.on(Hls.Events.LEVEL_SWITCHED, (_, d) => {
        const lvl = hls.levels[d.level];
        setLevel(lvl ? `${lvl.height}p` : "auto");
      });
      hlsRef.current = hls;
    }
    return () => { hlsRef.current?.destroy(); hlsRef.current = null; };
  }, [src]);

  return (
    <div className="player">
      <video
        ref={videoRef}
        onPlay={() => setPlaying(true)}
        onPause={() => setPlaying(false)}
        onTimeUpdate={(e) => setTime(e.currentTarget.currentTime)}
        onLoadedMetadata={(e) => setDuration(e.currentTarget.duration)}
      />
      <div className="controls">
        <button onClick={() => {
          const v = videoRef.current!;
          playing ? v.pause() : v.play();
        }}>{playing ? "Pause" : "Play"}</button>

        <input
          type="range"
          min={0}
          max={duration || 0}
          step={0.1}
          value={time}
          onChange={(e) => {
            const v = videoRef.current!;
            v.currentTime = Number(e.target.value);
          }}
        />

        <span>{fmt(time)} / {fmt(duration)}</span>
        <span className="quality">{level}</span>
      </div>
    </div>
  );
}

function fmt(s: number): string {
  if (!isFinite(s)) return "0:00";
  const m = Math.floor(s / 60);
  const ss = Math.floor(s % 60).toString().padStart(2, "0");
  return `${m}:${ss}`;
}

The quality readout is the part wrappers tend to hide. LEVEL_SWITCHED fires every time hls.js picks a new ABR rendition, and hls.levels[level] has the bitrate, resolution, and codec strings. Surfacing "now playing 720p" in the corner of your player is a five-line feature that meaningfully changes how power users perceive your product.

4. Manual quality picker

Some users will want to force a quality, usually because they don't trust ABR or because they're on a metered connection. Wire it like this:

const [levels, setLevels] = useState<Hls["levels"]>([]);

useEffect(() => {
  const hls = hlsRef.current;
  if (!hls) return;
  hls.on(Hls.Events.MANIFEST_PARSED, () => setLevels(hls.levels));
}, []);

// in JSX:
<select
  value={hls.currentLevel}
  onChange={(e) => { hls.currentLevel = Number(e.target.value); }}
>
  <option value={-1}>Auto</option>
  {levels.map((l, i) => (
    <option key={i} value={i}>{l.height}p ({Math.round(l.bitrate / 1000)} kbps)</option>
  ))}
</select>

-1 means "let ABR pick"; any non-negative index pins the player to that level. After a user pins to 480p, the seek bar still works and the rest of ABR's logic still runs underneath, but the renderer stays at 480p.

5. The error recovery loop (do not skip)

This is the single thing the wrappers were doing that you actually need.

hls.on(Hls.Events.ERROR, (_, data) => {
  if (!data.fatal) return;

  if (data.type === Hls.ErrorTypes.NETWORK_ERROR) {
    console.warn("hls: network error, restarting load");
    hls.startLoad();
    return;
  }
  if (data.type === Hls.ErrorTypes.MEDIA_ERROR) {
    console.warn("hls: media error, recovering");
    hls.recoverMediaError();
    return;
  }
  console.error("hls: fatal", data);
  hls.destroy();
});

Three rules:

1. Ignore non-fatal errors. hls.js retries those itself.
2. Network errors get a fresh startLoad(). This is what saves a viewer who walked into a tunnel.
3. Media errors get recoverMediaError(). This rebuilds the MSE source buffers, which is the only thing that fixes "the decoder gave up after a corrupt segment."

Add a tiny rate limiter in production. If recoverMediaError fails twice within a few seconds, destroy and recreate the Hls instance with a fresh source. Otherwise you can wedge yourself into an infinite recovery loop.

6. Buffer indicator

Showing "this video is buffering" properly means listening to the right events, not just paused.

const [stalled, setStalled] = useState(false);

const v = videoRef.current!;
v.addEventListener("waiting", () => setStalled(true));
v.addEventListener("playing", () => setStalled(false));

For the YouTube-style "this much of the video is buffered ahead" bar, use videoElement.buffered:

const buffered = videoRef.current?.buffered;
let aheadPct = 0;
if (buffered && buffered.length > 0 && duration > 0) {
  aheadPct = (buffered.end(buffered.length - 1) / duration) * 100;
}

Render a second <progress> underneath the seek bar at that percentage. Total time invested: ten minutes.

7. Subtitles

hls.js parses WebVTT tracks from the manifest into audioTracks and subtitleTracks. Toggle them like:

hls.subtitleDisplay = true;
hls.subtitleTrack = 0;        // -1 to disable

For language selection, hls.subtitleTracks is an array with name, lang, and default flags.

8. Cleanup checklist

Things people forget that bite later:

Mistake	Symptom
No hls.destroy() in unmount	Memory leak, Chrome devtools shows climbing JS heap
Forgetting Safari native path	App works in Chrome dev, breaks on iPhone in QA
Listening to pause instead of waiting for buffering	Players show "buffering" when the user manually pauses
Not handling MEDIA_ERROR	Random unrecoverable freezes on bad-CDN nights
Hls.isSupported() === false ignored	Old browsers show a broken player with no fallback

What's next

There are three places to take this once it's running:

• Picture-in-Picture. videoRef.current.requestPictureInPicture(). One line, free feature.
• MediaSession metadata. Set navigator.mediaSession.metadata so the OS lock screen shows the right title and artwork.
• Player telemetry. Subscribe to Hls.Events.FRAG_LOADED and send the per-segment timings to your analytics. This is gold for debugging "the video stalled, but only for users in Brazil."

If you're playing assets from a managed video API (Mux, FastPix, Cloudflare Stream, api.video), most of them ship their own custom-element player that wires telemetry for you. Use it if you want the analytics for free. Build your own when the player UX is part of the product.

The 1.7 line of hls.js looks promising for interstitial ads and a cleaner LL-HLS toggle. Worth watching the hls.js releases page for the stable 1.7.0 cut later this year.

Happy playing.