react-player

library3.4.0jsnpmunverified

ReactPlayer is a highly versatile React component designed for embedding and controlling various media sources directly within a web application. It supports a wide array of popular platforms, including YouTube, Vimeo, Wistia, TikTok, Spotify, and Twitch, as well as generic file paths, HLS, and DASH streams. The current stable version is 3.4.0. The library underwent a significant architectural rewrite in v3, transitioning to TypeScript and enhancing its modularity. Maintenance has been officially taken over by Mux, indicating a commitment to more frequent updates and fixes, ensuring its adaptability to evolving media platforms and web standards. Its key differentiators include broad support for numerous media providers and the ability to dynamically load players, which helps reduce initial bundle size when code splitting is enabled.

web-framework communication

npm install react-player

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-PLAYER

react-player

web-frameworkjavascriptv3.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ReactPlayer

✓ import ReactPlayer from 'react-player'

✗ const ReactPlayer = require('react-player')

This is the primary way to import the component. CommonJS `require` is not directly supported for default exports.

ReactPlayer (Lazy Loading)

✓ import ReactPlayer from 'react-player/lazy'

Use this import for dynamic, code-split loading of players, reducing initial bundle size. Your build system must support `import()` statements.

ReactPlayerProps

✓ import { ReactPlayerProps } from 'react-player'

✗ import { PlayerProps } from 'react-player'

Import the type definition for the component's props for use in TypeScript projects.

Demonstrates a basic ReactPlayer setup with playback controls, volume adjustment, and mute functionality for a YouTube video.

import React, { useState } from 'react'; import ReactPlayer from 'react-player'; function MyVideoPlayer() { const [playing, setPlaying] = useState(false); const [volume, setVolume] = useState(0.8); const [muted, setMuted] = useState(false); return ( <div style={{ width: '640px', height: '360px' }}> <h3>Now Playing: ReactPlayer Demo</h3> <ReactPlayer url='https://www.youtube.com/watch?v=LXb3EKWsInQ' playing={playing} controls={true} volume={volume} muted={muted} width='100%' height='100%' onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onVolumeChange={val => setVolume(val)} /> <div style={{ marginTop: '10px' }}> <button onClick={() => setPlaying(!playing)}> {playing ? 'Pause' : 'Play'} </button> <button onClick={() => setMuted(!muted)} style={{ marginLeft: '10px' }}> {muted ? 'Unmute' : 'Mute'} </button> <input type='range' min={0} max={1} step='any' value={volume} onChange={e => setVolume(parseFloat(e.target.value))} style={{ marginLeft: '10px', width: '100px' }} /> <span>{(volume * 100).toFixed(0)}%</span> </div> </div> ); } export default MyVideoPlayer;

Debug

Known issues

breakingVersion 3.0.0 introduced a complete rewrite in TypeScript with a new architecture. It is not backwards compatible with v2. Projects upgrading from v2 must consult the migration guide for breaking changes.

fix

Refer to the official migration guide for `react-player` when upgrading from v2 to v3 to understand necessary code changes and prop adjustments.

affects: >=3.0.0

gotchaModern browsers (e.g., Chrome 66+) often block autoplay for videos that are not muted or without prior user interaction. Some specific players (like Facebook) may not allow unmuting until a user directly interacts.

fix

To enable autoplay, set the `muted={true}` prop on `ReactPlayer`. For unmuting, consider providing native controls (`controls={true}`) or a custom UI element that requires user interaction.

affects: >=1.0.0

gotchaWhen trying to hide controls for Vimeo videos using `controls={false}`, the functionality might be overridden by the video owner's settings on Vimeo. This is not a limitation of ReactPlayer but of Vimeo's platform.

fix

Ensure that the Vimeo video's privacy settings allow embedding and control customization. If controls persist, it's an upstream limitation by the video host.

affects: >=1.0.0

gotchaThe primary prop for specifying the media URL is `url`, not `src`, which might be a common intuition from native HTML5 video elements. Using `src` instead of `url` will prevent the player from loading media.

fix

Always use the `url` prop to pass the media source to `ReactPlayer`, e.g., `<ReactPlayer url='https://example.com/video.mp4' />`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'play')

Attempting to call a method (like `play()`, `seekTo()`) on a `ReactPlayer` ref before the component is fully mounted, the internal player is ready, or after the component has unmounted.

fix

Ensure the ref is assigned and the `onReady` callback has fired before interacting with player methods. Use conditional rendering or an `if (playerRef.current)` check before calling methods.

Warning: Failed prop type: The prop `url` is marked as required in `ReactPlayer`, but its value is `undefined`.

The `url` prop was either not provided or evaluated to `undefined` when the `ReactPlayer` component was rendered.

fix

Always provide a valid string URL to the `url` prop of `ReactPlayer`. Double-check variable names or conditional logic that might result in an undefined `url`.

DOMException: play() failed because the user didn't interact with the document first.

The browser's autoplay policy blocked the `play()` action, typically because the video was not muted and there was no prior user interaction with the page.

fix

Set the `muted={true}` prop on `ReactPlayer` to allow autoplay. For unmuted playback, ensure a user interaction (like a click) precedes or triggers the `play()` call.

ReferenceError: ReactPlayer is not defined

This usually occurs in CommonJS environments when trying to `require('react-player')` and access it directly, or when there's a typo in the import statement.

fix

For CommonJS, use `const ReactPlayer = require('react-player').default;` if using `require`. For ES Modules, ensure the import statement is `import ReactPlayer from 'react-player';` and there are no typos.

Upgrade

Version history

3.4.0latest on npm

Audit

Dependencies

reactrequiredCore peer dependency for any React component.

react-domrequiredCore peer dependency for rendering React components to the DOM.

@types/reactoptionalRequired for TypeScript users to ensure type compatibility with React.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cookpete/react-player ↗

packagehttps://www.npmjs.com/package/react-player ↗

homepagehttps://www.npmjs.com/package/react-player ↗