react-player

ReactPlayer is a React component that renders a unified player for a wide range of media sources — YouTube, Vimeo, Wistia, Mux, Twitch, TikTok, Spotify, HLS and DASH streams, and native file URLs — behind a single consistent API. Instead of hand-rolling separate embeds and SDK integrations for every provider, developers pass a src URL and ReactPlayer detects the source and swaps in the matching player automatically.

Version 3 rebuilt the library around a family of custom-element packages (hls-video-element, youtube-video-element, vimeo-video-element, and similar), each lazily loaded via React.lazy so unused providers never ship in the main bundle. The project is now co-maintained with Mux, the video infrastructure company, which has taken over ongoing maintenance and release cadence.

What You Get

• A single <ReactPlayer src=”…” /> component that auto-detects and plays YouTube, Vimeo, Wistia, Mux, Twitch, TikTok, Spotify, HLS, DASH, and native file URLs
• Lazy-loaded, per-provider code splitting via React.lazy so only the player you actually use ships to the browser
• A consistent callback API (onReady, onStart, onPlay, onProgress, onDurationChange, onEnded, onError, etc.) that normalizes events across every provider
• Light mode that renders a lazy-loaded thumbnail preview and defers loading the real player until the user clicks
• Support for picture-in-picture, custom players via addCustomPlayer, and native <source>/<track> children for multi-source and subtitle tracks

Common Use Cases

• Embedding a single video or audio player in a marketing site without writing separate integration code for every provider a client might paste in
• Building a media dashboard or CMS preview pane that must play arbitrary user-submitted URLs from YouTube, Vimeo, or direct file links
• Wiring ReactPlayer into Media Chrome for a fully custom-branded set of playback controls
• Deferring player and SDK downloads behind a click-to-play thumbnail on content-heavy pages to improve initial load time

Under The Hood

Architecture ReactPlayer is built around a small factory function, createReactPlayer, that takes an ordered list of PlayerEntry objects (players.ts) plus a fallback and returns the public ReactPlayer component. Each entry pairs a canPlay(url) matcher (patterns.ts, mostly regexes tested against src) with a lazily imported provider component; when ReactPlayer.tsx mounts, getActivePlayer walks the list — including any players registered via addCustomPlayer — and hands the first match to Player.tsx, which forwards refs, filters out ReactPlayer-only event handlers, and normalizes playback state (play/pause, volume, playbackRate, picture-in-picture) onto whichever underlying element was selected. Because every provider shares the same PlayerEntry shape, adding a new source is a matter of writing one canPlay matcher and one lazy import, and the light-mode preview and Suspense fallback both live at the ReactPlayer.tsx level rather than being duplicated per provider.

Tech Stack The library is authored in strict TypeScript (tsconfig.json enables strict) with React as a peer dependency across several major versions, and it deliberately outsources per-provider playback to a family of custom-element packages — hls-video-element, dash-video-element, youtube-video-element, vimeo-video-element, wistia-video-element, twitch-video-element, tiktok-video-element, spotify-audio-element, and a Mux player package — each pulled in as a real dependency and loaded through React.lazy so unused providers are code-split out of the main bundle. Builds run through an in-repo esbuild-based builder script rather than a general-purpose bundler, tests run via a custom tester harness on top of a lightweight assertion library and spies, with coverage tooling layered on top, and a fast linter/formatter handles style; CI workflows run these checks on every push.

Code Quality Tests live under test/ and exercise both the public ReactPlayer surface (static methods, instance methods, and prop handling) and the lower-level Player component in isolation, using assertions and stubs rather than a mainstream framework like Jest or Vitest. Error handling favors silent no-ops for browser API edge cases — for example, picture-in-picture requests are wrapped in empty try/catch blocks — which keeps playback from throwing but also means such failures aren’t surfaced to consumers. Naming is consistent (PlayerEntry, canPlay, activePlayer) and CI enforces linting and the test suite on every push, though the codebase carries comparatively light inline documentation, relying instead on the README and a dedicated migration guide for usage guidance.

API Design ReactPlayer’s most distinctive choice is delegating actual playback to standards-based custom elements rather than hand-rolled iframe/SDK wrappers — the same underlying elements can be used directly outside React, which is why ReactPlayer pairs naturally with Media Chrome for fully custom controls. The public API stays minimal: a single src prop plus a flat set of HTMLMediaElement-shaped props and callbacks (onReady, onProgress, onEnded, etc.), and extensibility is opt-in via addCustomPlayer rather than requiring users to fork the library to add a provider. This lowers boilerplate for the common case of one component and one src while still giving power users a documented extension point.