ReactPlayer
A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, DailyMotion and Kaltura. Not using React? No problem.
Migrating to ReactPlayer v2.0
ReactPlayer v2.0 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.
Usage
By default, ReactPlayer supports many different types of url. If you only ever use one type, use imports such as react-player/youtube to reduce your bundle size. See config keys for all player keys.
If your build system supports import[] statements, use react-player/lazy to lazy load the appropriate player for the url you pass in. This adds several reactPlayer chunks to your output, but reduces your main bundle size.
Demo page: //cookpete.com/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.
Polyfills
- If you are using npm and need to support browsers without Promise you will need a Promise polyfill.
- To support IE11 you will need to use babel-polyfill or a similar ES2015+ polyfill.
Autoplay
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}.
Props
| url | The url of a video or song to play Can be an array or MediaStream object | |
| 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 | 640px |
| height | Set the height of the player | 360px |
| style | Add inline styles to the root element | {} |
| progressInterval | The time between onProgress callbacks, in milliseconds | 1000 |
| 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 |
| stopOnUnmount | If you are using pip you may want to use stopOnUnmount={false} to continue playing in picture-in-picture mode even after ReactPlayer unmounts | true |
| 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 | div |
| 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 |
| config | Override options for the various players, see config prop |
Callback props
Callback props take a function that gets fired on various player events:
| 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 media starts or resumes playing after pausing or buffering |
| onProgress | Callback containing played and loaded progress as a fraction, and playedSeconds and loadedSeconds in seconds eg { played: 0.12, playedSeconds: 11.3, loaded: 0.34, loadedSeconds: 16.7 } |
| onDuration | Callback containing duration of the media, in seconds |
| onPause | Called when media is paused |
| onBuffer | Called when media starts buffering |
| onBufferEnd | Called when media has finished buffering Works for files, YouTube and Facebook |
| onSeek | Called when media seeks with seconds parameter |
| 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 |
| onClickPreview | Called when user clicks the light mode preview |
| onEnablePIP | Called when picture-in-picture mode is enabled |
| onDisablePIP | Called when picture-in-picture mode is disabled |
Config prop
There is a single config prop to override settings for each type of player:
Settings for each player live under different keys:
| youtube | playerVars: Override the default player vars embedOptions: Override the default embed options onUnstarted: Called when state changes to unstarted [usually when video fails to autoplay] |
| appId: Your own Facebook app ID version: Facebook SDK version playerId: Override player ID for consistent server-side rendering [use with react-uid] attributes: Extra data attributes to pass to the fb-video element | |
| soundcloud | options: Override the default player options |
| vimeo | playerOptions: Override the default params |
| wistia | options: Override the default player options playerId: Override player ID for consistent server-side rendering [use with react-uid] |
| mixcloud | options: Override the default player options |
| dailymotion | params: Override the default player vars |
| twitch | options: Override the default player options playerId: Override player ID for consistent server-side rendering [use with react-uid] |
| file | attributes: Apply element attributes forceVideo: Always render a element forceAudio: Always render an element forceHLS: Use hls.js for HLS streams forceDASH: Always use dash.js for DASH streams forceFLV: Always use flv.js hlsOptions: Override the default hls.js options hlsVersion: Override the hls.js version loaded from jsdelivr, default: 0.13.1 dashVersion: Override the dash.js version loaded from cdnjs, default: 2.9.2 flvVersion: Override the flv.js version loaded from jsdelivr, default: 1.5.0 |
Methods
Static Methods
| ReactPlayer.canPlay[url] | 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 attemping to play. Any URL that does not match any patterns will fall back to a native HTML5 media player. |
| ReactPlayer.canEnablePiP[url] | Determine if a URL can be played in picture-in-picture mode |
| ReactPlayer.addCustomPlayer[CustomPlayer] | Add a custom player. See Adding custom players |
| ReactPlayer.removeCustomPlayers[] | Remove any players that have been added using addCustomPlayer[] |
Instance Methods
Use ref to call instance methods on the player. See the demo app for an example of this.
| seekTo[amount, type] | Seek to the given number of seconds, or fraction if amount is between 0 and 1 type parameter lets you specify 'seconds' or 'fraction' to override default behaviour |
| getCurrentTime[] | Returns the number of seconds that have been played Returns null if unavailable |
| getSecondsLoaded[] | Returns the number of seconds that have been loaded Returns null if unavailable or unsupported |
| getDuration[] | Returns the duration [in seconds] of the currently playing media Returns null if duration is unavailable |
| getInternalPlayer[] | Returns the internal player of whatever is currently playing eg the YouTube player instance, or the element when playing a video file Use getInternalPlayer['hls'] to get the hls.js player Use getInternalPlayer['dash'] to get the dash.js player Returns null if the internal player is unavailable |
| showPreview[] | When using light mode, returns to the preview overlay |
Advanced Usage
Light player
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.
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.
Responsive player
Set width and height to 100% and wrap the player in a fixed aspect ratio box to get a responsive player:
See jsFiddle example
SDK Overrides
You can use your own version of any player SDK, assuming the correct window global is set before the player mounts. For example, to use a local version of hls.js, add to your app. If window.Hls is available when ReactPlayer mounts, it will use that instead of loading hls.js from cdnjs. See #605 for more information.
Standalone player
If you arent using React, you can still render a player using the standalone library:
See jsFiddle example
Adding custom players
If you have your own player that is compatible with ReactPlayers internal architecture, you can add it using addCustomPlayer:
Use removeCustomPlayers to clear all custom players:
It is your responsibility to ensure that custom players keep up with any internal changes to ReactPlayer in later versions.
Mobile considerations
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 element, in certain mobile browsers [such as Chrome and Safari], only allows playback to take place if its initiated by a user interaction [such as tapping on the player].
Multiple Sources and Tracks
Passing an array of YouTube URLs to the url prop will load them as an untitled playlist.
When playing file paths, an array of sources can be passed to the url prop to render multiple tags.
You can also specify a type for each source by using objects with src and type properties.
elements for subtitles can be added using config.file:
Supported media
- YouTube videos use the YouTube iFrame Player API
- Facebook videos use the Facebook Embedded Video Player API
- SoundCloud tracks use the SoundCloud Widget API
- Streamable videos use Player.js
- Vidme videos are no longer supported
- Vimeo videos use the Vimeo Player API
- Wistia videos use the Wistia Player API
- Twitch videos use the Twitch Interactive Frames API
- DailyMotion videos use the DailyMotion Player API
- Vidyard videos use the Vidyard Player API
- Kaltura's react-player implementation uses the embed.ly Player.js API but Kaltura specific APIs are also available, see Kaltura Player API
- Supported file types are playing using or elements
- HLS streams are played using hls.js
- DASH streams are played using dash.js
Contributing
See the contribution guidelines before creating a pull request.
Thanks
- Thanks to anyone who has contributed.
- Huge thanks to my Patreon sponsors:
Joseph Fung |
Hi CookPete,
I have a problem about iOS9 with attribute 'autoplay' in html5 tag. When I use , the autoplay attribute seems not add attribute 'autoplay' to. And iOS has limitation to block autoplay to prevent wasted bandwidth from user's quota. But we want to make a repeat function with playlist in iOS. So I try to run these code after componentDidMount: .... var audio = document.querySelector["audio"]; audio.autoplay = true; audio.load[]; //iOS9 need do this first audio.play[]; //after iOS 5.x do this to trigger audio to play URL resource. ....
It can work on simple sample without ReactPlayer, just use audio tag and set resource and do that steps which I run after componentDidMount. But ReactPayer cannot, because it create two audio tag in the same time. First player is SoundCloud, second is FilePlayer. I cannot select correct audio tag, because document.querySelector always only return the first target it found[not array, I don't why].
So my solution in function componentDidMount is :
.... var audio = document.querySelector["audio"]; audio.remove[]; //I know this is point towhich use for SoundCloud Player audio = document.querySelector["audio"]; //re-select audio again, this is point to FilePlayer which I want. audio.autoplay = true; audio.load[]; //iOS9 need do this first audio.play[]; //after iOS 5.x do this to trigger audio to play URL resource. ....
I know this solution is not good, so I hope you can provide a method or prop for user[developer] to decide which player they really want to use only, not all player which can current URL resource.
Here is committed log that you did in 15 Dec 2015.
You add a map to generate each player which can play url resource. Maybe you have some consideration, I really hope you can help me to solve this problem. This library is very useful for me, so I hope it can be better than past.
Thanks!
Regards Kevin.Chien
Be sure to search for your issue before opening a new one.
Current Behavior
I just do not know what to do anymore after searching over the web over the last few days. It's obviously a lack of experience from my side so help would be very appreciated.
I'm rendering an array of sections with react using hooks, so we can see a page with many sections that contains a video. In each section ListItem, I have a ReactPlayer video Item. When I'm hovering a section, onMouseEnter of that section only, ALL videos of every sections start playing which is not what I want.
Expected Behavior
I want to hover a section and start playing that video Item of that section only. Important that I want to do this on hovering the section and not the video Item.
Steps to Reproduce
- So far I'm passing a function parent to child holding the state play of that video item which is a boolean for that video, but I know I should use some index and or useRef to identify where it's coming from, but kind of lost here.
Environment
- URL attempting to play:
- Browser: Firefox, chrome
- Operating system: mac os
Other Information
Current Behavior
We use the onReady hook to do some initialization [resizing based on video size, show correct background color, etc.] before showing a video. This works fine for all combinations of video sources [YouTube, Vimeo, etc.] and platforms [native Android, native iOS, web, etc.] except for the combination: Vimeo Live Event on native iOS [iPhone and iPad]. In that particular combination, the onReady is not fired and therefore our initialization is not executed and the video is not shown. If we use reactplayer to show a "standard" Vimeo video, the onReady is fired.
iPhone / iPad with a Vimeo live link [e.g. //vimeo.com/event/1234567890/0987654321]: onReady is not fired. iPhone / iPad with a Vimeo video link [e.g. //vimeo.com/1234567890/0987654321]: onReady is fired.
On web [also web on iPhone / iPad] and native Android, the onReady is fired for a Vimeo live link.
Expected Behavior
That onReady is fired for a Vimeo live event video on native iOS.
Steps to Reproduce
- Create a Vimeo live event.
- Copy the URL, something like //vimeo.com/event/1234567890/0987654321 or //vimeo.com/event/1234567890 [depending if it's a public or private video]
- Initialize ReactPlayer with the onReady hook, e.g. {alert["ready!"]}} />
- Run on native iOS [iPad or iPhone].
- The onReady hook is not fired and no alert is shown. When running on native Android or web, the hook is fired and the alert is shown.
Environment
React 17.0.2 Ionic React 5.6.12 ReactPlayer 2.9.0 iPhone X with iOS 15.1 or iPad 8th gen with iOS 14.6
Other Information
No