# react-player 3.4.0: one React component for YouTube, Vimeo, HLS, DASH and file playback

> react-player is a React component that routes a src URL to the appropriate player backend, covering YouTube, Vimeo, HLS, DASH, Mux and file paths through one API. Version 3.4.0, now maintained by Mux, is not backwards compatible with v2 and ships with a migration guide.

**cookpete/react-player** — A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion

- Repository: https://github.com/cookpete/react-player
- Website: https://cookpete.github.io/react-player
- Stars: 10,292 · Forks: 1,202
- Language: TypeScript
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/cookpete-react-player

## URL routing: one component resolves the address and loads the matching player SDK

react-player accepts a src string and dispatches it to the correct player backend: a YouTube URL triggers the YouTube SDK, an HLS stream URL triggers the HLS player, a file path routes to the browser's native video element. The caller never selects the backend directly. The same ReactPlayer component renders on every source, and the correct engine loads behind it.

Playback is controlled through props, including playing, loop, volume, and muted. Callback props let the application respond to events like buffering, seeking, or the media ending. Because the prop surface does not change between sources, switching a src from a file path to a YouTube URL does not require rewriting the event-handling code that surrounds the component.

The cost of that uniform interface is that the component must maintain a separate integration layer for each supported source. Features that one player exposes but another does not produce props that silently have no effect on unsupported sources, with no error to indicate that the prop was ignored. That silence can hide configuration bugs.

## Installing react-player 3.4.0 and rendering a first YouTube video

react-player is published on npm under the name react-player, so adding it to a project takes one command:

```bash
npm install react-player
```

Yarn users can run `yarn add react-player` instead. Once installed, import the component and pass a src:

```jsx
import React from 'react'
import ReactPlayer from 'react-player'

// Render a YouTube video player
<ReactPlayer src='https://www.youtube.com/watch?v=LXb3EKWsInQ' />
```

The component defaults to a width of 320px and a height of 180px. Both can be overridden with the width and height props, and inline styles can be passed via the style prop. A live demo is available at https://cookpete.github.io/react-player, which is a practical first step for confirming that a source URL will play before writing application code around it.

For environments that cannot use npm modules directly, a minified version of react-player lives in the dist directory after installing. To generate that file manually, the README says to check out the repository and run `npm run build:dist`.

## Code splitting loads only the player chunk each src needs, shrinking the main bundle

When a build system supports import() statements and code splitting, react-player can lazy load the specific player implementation for each src. Enabling that mode adds several reactPlayer chunks to the output, but the main bundle becomes smaller because unused player code is deferred rather than bundled upfront; the README presents this as a deliberate trade-off for the caller to evaluate.

The trade-off is concrete: the default import bundles all player SDKs together, which is simpler but larger. With code splitting enabled, the main bundle shrinks and the player code is deferred until a src is actually rendered. For applications that play only one type of media, that deferred cost is small. For applications that mix YouTube, HLS and file playback on the same page, each player chunk is loaded as it becomes necessary.

The README does not document exact bundle sizes for either path. A project adopting react-player for the first time would need to measure the output in their own build setup to decide whether lazy loading is worth the extra complexity in chunk naming and cache management.

## playbackRate and picture-in-picture apply only to certain sources, not all

Several props in the API are silently ignored for sources that do not support them. The playbackRate prop sets playback speed, but the README lists only three sources where it takes effect: YouTube, Wistia, and file paths. The pip prop, which toggles picture-in-picture mode, is available only when playing file URLs in browsers that implement the picture-in-picture API.

Rate change events have the same narrow scope. The onRateChange callback fires on YouTube, Wistia, and file paths; for Vimeo it fires only when the video's owner has configured their Vimeo account to allow rate changes on embedded players. Passing any of these props on an unsupported source produces no error; the component ignores them without signaling anything to the caller.

The controls prop defaults to false, but there is a Vimeo exception: when a Vimeo video's owner has not configured embedded players to hide the controls bar, the controls bar appears even if the prop is set to false. A caller who sets controls={false} on a Vimeo source and sees the bar anyway is encountering a Vimeo account setting, not a bug in react-player.

## Autoplay requires muted={true} since Chrome 66, and Facebook cannot be unmuted by code

Starting with Chrome 66, a browser-level autoplay policy blocks any video that is not already muted from playing without user interaction. The README links to a Chrome announcement documenting this change. Setting muted={true} on the ReactPlayer component is the required step to make autoplay work in those browsers.

Facebook sources add a second layer of restriction at the platform level: the audio on a Facebook video is locked until the viewer clicks or taps the player. Setting volume or muted programmatically has no effect before that interaction happens. The README recommends enabling the controls prop so the viewer has a visible way to unmute, which is the only path available given the platform restriction.

Neither of these is a react-player bug or a configuration gap. Both are external policies that the component documents but cannot bypass. An application that expects background audio from Facebook media, or that needs to control volume before user interaction, will not get what it expects from this source.

## Nineteen callback props cover playback state, with onEnded silent when loop is on

react-player exposes nineteen callback props for playback events. The list covers the states a player can enter: onReady fires when media is loaded, onStart when playing begins, onPlay when the playing prop is set to true, onPlaying when audio or video actually starts, onPause on pause, onEnded when playback finishes, and onError on failure. Finer-grained callbacks include onProgress for data loading, onTimeUpdate for current time changes, onDurationChange for duration, onWaiting for buffering, onSeeking and onSeeked for seek operations, and onEnterPictureInPicture and onLeavePictureInPicture for pip transitions.

One documented exception: onEnded does not fire when the loop prop is set to true, because the media restarts rather than ending. Applications that track how many times something played, or that need to take an action when content finishes, cannot rely on onEnded when looping is active. A different tracking approach is required in that case.

The distinction between onPlay and onPlaying matters for sources with buffering delays. onPlay fires when the playing prop changes to true; onPlaying fires when the media actually starts producing output. For large files or slow streams, those two events may be separated by a noticeable interval, and treating them as equivalent will miscount play starts.

## v3 is not backwards compatible with v2, Mux now maintains it, and MIGRATING.md is the upgrade path

v3 rewrites the internal architecture, and the new API breaks the existing prop surface from v2. MIGRATING.md at the repository root covers what changed; anyone updating the package version on an existing v2 application should read it first, before the update, not after encountering errors.

Mux took over maintenance of the project. The README indicates the project will continue under MIT and will see a higher release cadence than before. v3.4.0 is the latest release, published on 2025-11-13. The two prior releases were v3.3.3 on 2025-09-19 and v3.3.2 on 2025-08-25. The repository was last pushed on 2026-10-03 and is not archived.

The codebase is TypeScript. The package.json marks it as "type": "module", so it ships as ES modules. Published output is in dist/, and source is under src/. A CHANGELOG.md and a CONTRIBUTING.md sit at the repository root alongside LICENSE.md, which is the MIT text to check before redistribution.

## Conclusion

Use react-player when you need one component to handle playback across YouTube, Vimeo, HLS, DASH and file paths in a React app and the MIT license suits your project. Skip it if you need a player that works outside React, or if v2 features you depend on are not yet ported in MIGRATING.md. Before adopting v3, read MIGRATING.md to confirm your current props and callbacks are still supported, test autoplay with muted={true} on your target browsers, and verify that playbackRate and pip work for the specific sources your app plays.

## FAQ

### How do I install react-player?

Run npm install react-player or yarn add react-player. For environments without npm, a minified build lives in the dist directory after installing, or you can generate it by checking out the repository and running npm run build:dist.

### Is react-player compatible with v2?

Version 3 is not backwards compatible with v2. The repository includes a MIGRATING.md file at the root that documents the changes needed to upgrade.

### Does react-player support autoplay?

Autoplay requires muted={true} in browsers following the Chrome 66 policy. Facebook videos have an additional restriction: they cannot be unmuted until the user interacts with the video.

### Who maintains react-player?

Maintenance has been taken over by Mux, a video API company. The README says the project will remain open source under the MIT license with a higher rate of fixes and releases. The latest release is v3.4.0, published on 2025-11-13.

### Which video sources does react-player support?

According to the README, react-player supports file paths, HLS streams, DASH streams, YouTube, Vimeo, Wistia and Mux. The repository topics also include DailyMotion, Facebook, SoundCloud, Streamable and Twitch.

## Sources

- [cookpete/react-player on GitHub](https://github.com/cookpete/react-player)
- [License: MIT](https://github.com/cookpete/react-player/blob/master/LICENSE)
- [Project website](https://cookpete.github.io/react-player)
- [README](https://github.com/cookpete/react-player/blob/master/README.md)
- [Releases](https://github.com/cookpete/react-player/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cookpete-react-player