react-player

by cookpete

cookpete / react-player

A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, So...

4.5K Stars 662 Forks Last release: Not found MIT License 858 Commits 131 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

ReactPlayer

Latest npm version Build Status Test Coverage Become a sponsor on Patreon

A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, and DailyMotion. 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

npm install react-player # or yarn add react-player
import React from 'react'
import ReactPlayer from 'react-player'

// Render a YouTube video player

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.
import React from 'react'
import ReactPlayer from 'react-player/youtube'

// Only loads the YouTube player

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.
import React from 'react'
import ReactPlayer from 'react-player/lazy'

// Lazy load the YouTube player

Demo page:

https://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

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.

Props

Prop

Description Default

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
wrapper
| Element or component to use as the container element |
div
playIcon
| Element or component to use as the play icon in light mode
config
| Override options for the various players, see config prop

Callback props

Callback props take a function that gets fired on various player events:

Prop

Description

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
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:

Key

Options

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)
facebook
|
appId
: Your own Facebook app ID
version
: Facebook SDK version
playerId
: Override player ID for consistent server-side rendering (use with
react-uid
)
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

Method

Description

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.

Method

Description

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:
class ResponsivePlayer extends Component {
  render () {
    return (
      
) } }
.player-wrapper {
  position: relative;
  padding-top: 56.25% /* Player ratio: 100 / (1280 / 720) */
}

.react-player { position: absolute; top: 0; left: 0; }

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 aren’t 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 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.

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 it’s 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

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

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.