
Security News
ECMAScript 2025 Finalized with Iterator Helpers, Set Methods, RegExp.escape, and More
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
react-player
Advanced tools
A React component for playing a variety of URLs, including file paths, Mux, YouTube, Vimeo, and Wistia
The react-player npm package is a React component for playing various types of media, including YouTube, SoundCloud, Vimeo, and more. It provides a simple interface for embedding media players in React applications.
Playing YouTube Videos
This feature allows you to embed and play YouTube videos in your React application. The URL of the YouTube video is passed as a prop to the ReactPlayer component.
<ReactPlayer url='https://www.youtube.com/watch?v=ysz5S6PUM-U' />
Playing Vimeo Videos
This feature allows you to embed and play Vimeo videos. Similar to YouTube, you pass the Vimeo video URL as a prop to the ReactPlayer component.
<ReactPlayer url='https://vimeo.com/123456789' />
Playing SoundCloud Tracks
This feature allows you to embed and play SoundCloud tracks. The SoundCloud track URL is passed as a prop to the ReactPlayer component.
<ReactPlayer url='https://soundcloud.com/artist/track' />
Customizing Player Controls
This feature allows you to enable or disable player controls. By setting the 'controls' prop to true, you can display the default player controls.
<ReactPlayer url='https://www.youtube.com/watch?v=ysz5S6PUM-U' controls={true} />
Playing Local Media Files
This feature allows you to play local media files by providing the file path as a prop to the ReactPlayer component.
<ReactPlayer url='path/to/local/file.mp4' />
The video-react package is a web video player built from the ground up for an HTML5 world using React library. It provides a set of React components for building video players with custom controls. Compared to react-player, video-react is more focused on HTML5 video and offers more customization options for the player controls.
The react-video-js-player package is a React component for Video.js, a popular HTML5 video player. It provides a simple interface for integrating Video.js into React applications. Compared to react-player, react-video-js-player is specifically designed for Video.js and offers more advanced features for video playback and customization.
The react-h5-audio-player package is a customizable audio player component for React. It provides a simple interface for embedding audio players with custom controls. Compared to react-player, react-h5-audio-player is focused solely on audio playback and offers more customization options for audio player controls.
A React component for playing a variety of URLs, including file paths, HLS, DASH, YouTube, Vimeo, Wistia and Mux.
Version 3 of ReactPlayer is a major update with a new architecture and many new features. It is not backwards compatible with v2, so please see the migration guide for details.
Using Next.js and need to handle video upload/processing? Check out next-video.
Maintenance of ReactPlayer is being taken over by Mux. Mux is a video api for developers. The team at Mux have worked on many highly respected projects and are committed to improving video tooling for developers.
ReactPlayer will remain open source, but with a higher rate of fixes and releases over time. Thanks to everyone in the community for your ongoing support.
npm install react-player # or yarn add react-player
import React from 'react'
import ReactPlayer from 'react-player'
// Render a YouTube video player
<ReactPlayer src='https://www.youtube.com/watch?v=LXb3EKWsInQ' />
If your build system supports import()
statements and code splitting enable this to lazy load the appropriate player for the src
you pass in. This adds several reactPlayer
chunks to your output, but reduces your main bundle size.
Demo page: https://cookpete.github.io/react-player
The component parses a URL and loads in the appropriate markup and external SDKs to play media from various sources. Props can be passed in to control playback and react to events such as buffering or media ending. See the demo source for a full example.
For platforms without direct use of npm
modules, a minified version of ReactPlayer
is located in dist
after installing. To generate this file yourself, checkout the repo and run npm run build:dist
.
As of Chrome 66, videos must be muted
in order to play automatically. Some players, like Facebook, cannot be unmuted until the user interacts with the video, so you may want to enable controls
to allow users to unmute videos themselves. Please set muted={true}
.
Prop | Description | Default |
---|---|---|
src | The url of a video or song to play | undefined |
playing | Set to true or false to pause or play the media | false |
loop | Set to true or false to loop the media | false |
controls | Set to true or false to display native player controls.◦ For Vimeo videos, hiding controls must be enabled by the video owner. | false |
light | Set to true to show just the video thumbnail, which loads the full player on click◦ Pass in an image URL to override the preview image | false |
volume | Set the volume of the player, between 0 and 1 ◦ null uses default volume on all players #357 | null |
muted | Mutes the player ◦ Only works if volume is set | false |
playbackRate | Set the playback rate of the player ◦ Only supported by YouTube, Wistia, and file paths | 1 |
width | Set the width of the player | 320px |
height | Set the height of the player | 180px |
style | Add inline styles to the root element | {} |
playsInline | Applies the playsInline attribute where supported | false |
pip | Set to true or false to enable or disable picture-in-picture mode◦ Only available when playing file URLs in certain browsers | false |
fallback | Element or component to use as a fallback if you are using lazy loading | null |
wrapper | Element or component to use as the container element | null |
playIcon | Element or component to use as the play icon in light mode | |
previewTabIndex | Set the tab index to be used on light mode | 0 |
Callback props take a function that gets fired on various player events:
Prop | Description |
---|---|
onClickPreview | Called when user clicks the light mode preview |
onReady | Called when media is loaded and ready to play. If playing is set to true , media will play immediately |
onStart | Called when media starts playing |
onPlay | Called when the playing prop is set to true |
onPlaying | Called when media actually starts playing |
onProgress | Called when media data is loaded |
onTimeUpdate | Called when the media's current time changes |
onDurationChange | Callback containing duration of the media, in seconds |
onPause | Called when media is paused |
onWaiting | Called when media is buffering and waiting for more data |
onSeeking | Called when media is seeking |
onSeeked | Called when media has finished seeking |
onRateChange | Called when playback rate of the player changed ◦ Only supported by YouTube, Vimeo (if enabled), Wistia, and file paths |
onEnded | Called when media finishes playing ◦ Does not fire when loop is set to true |
onError | Called when an error occurs whilst attempting to play media |
onEnterPictureInPicture | Called when entering picture-in-picture mode |
onLeavePictureInPicture | Called when leaving picture-in-picture mode |
There is a single config
prop to override settings for each type of player:
<ReactPlayer
src={src}
config={{
youtube: {
color: 'white',
},
}}
/>
Settings for each player live under different keys:
Method | Description |
---|---|
ReactPlayer.canPlay(src) | Determine if a URL can be played. This does not detect media that is unplayable due to privacy settings, streaming permissions, etc. In that case, the onError prop will be invoked after attempting to play. Any URL that does not match any patterns will fall back to a native HTML5 media player. |
ReactPlayer.addCustomPlayer(CustomPlayer) | Add a custom player. See Adding custom players |
ReactPlayer.removeCustomPlayers() | Remove any players that have been added using addCustomPlayer() |
Use ref
to call instance methods on the player. See the demo app for an example of this. Since v3
, the instance methods aim to be compatible
with the HTMLMediaElement interface.
The light
prop will render a video thumbnail with simple play icon, and only load the full player once a user has interacted with the image. Noembed is used to fetch thumbnails for a video URL. Note that automatic thumbnail fetching for Facebook, Wistia, Mixcloud and file URLs are not supported, and ongoing support for other URLs is not guaranteed.
If you want to pass in your own thumbnail to use, set light
to the image URL rather than true
.
You can also pass a component through the light
prop:
<ReactPlayer light={<img src='https://example.com/thumbnail.png' alt='Thumbnail' />} />
The styles for the preview image and play icon can be overridden by targeting the CSS classes react-player__preview
, react-player__shadow
and react-player__play-icon
.
Set width
to 100%
, height
to auto
and add an aspectRatio
like 16 / 9
to get a responsive player:
<ReactPlayer
src="https://www.youtube.com/watch?v=LXb3EKWsInQ"
style={{ width: '100%', height: 'auto', aspectRatio: '16/9' }}
/>
You can use your own version of any player SDK by using NPM resolutions. For example, to use a specific version of hls.js
, add the following to your package.json
:
{
"resolutions": {
"hls.js": "1.6.2"
}
}
If you have your own player that is compatible with ReactPlayer’s internal architecture, you can add it using addCustomPlayer
:
import YourOwnPlayer from './somewhere';
ReactPlayer.addCustomPlayer(YourOwnPlayer);
Use removeCustomPlayers
to clear all custom players:
ReactPlayer.removeCustomPlayers();
It is your responsibility to ensure that custom players keep up with any internal changes to ReactPlayer in later versions.
Due to various restrictions, ReactPlayer
is not guaranteed to function properly on mobile devices. The YouTube player documentation, for example, explains that certain mobile browsers require user interaction before playing:
The HTML5
<video>
element, in certain mobile browsers (such as Chrome and Safari), only allows playback to take place if it’s initiated by a user interaction (such as tapping on the player).
Since v3
if the player supports multiple sources and / or tracks, it works the same as the native
<source
and <track>
elements in the HTML <video>
or <audio>
element.
<ReactPlayer controls>
<source src="foo.webm" type="video/webm">
<source src="foo.ogg" type="video/ogg">
<track kind="subtitles" src="subs/subtitles.en.vtt" srclang="en" default>
<track kind="subtitles" src="subs/subtitles.ja.vtt" srclang="ja">
<track kind="subtitles" src="subs/subtitles.de.vtt" srclang="de">
</ReactPlayer>
v3
ReactPlayer v3
is a major update with a new architecture and many new features. It is not backwards compatible with v2
, so please see the migration guide for details.
Some providers have not been updated for v3
, it is recommended to keep using v2
and vote to add this provider to v3
in discussions
v2
ReactPlayer v2
changes single player imports and adds lazy loading players. Support for preload
has also been removed, plus some other changes. See MIGRATING.md
for information.
<video>
or <audio>
elementshls.js
dash.js
<mux-player>
elementSee the contribution guidelines before creating a pull request.
![]() Jackson Doherty |
Joseph Fung |
8 May 2025
FAQs
A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion
The npm package react-player receives a total of 1,085,954 weekly downloads. As such, react-player popularity was classified as popular.
We found that react-player demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.