2.15.1 • Published 26 days ago

react-player v2.15.1

Weekly downloads
343,969
License
MIT
Repository
github
Last release
26 days ago

Using Next.js and need to handle video upload/processing? Check out next-video.

✨ The future of ReactPlayer

Maintenance of ReactPlayer is being taken over by Mux. 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.

Usage

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

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

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
<ReactPlayer url='https://www.youtube.com/watch?v=LXb3EKWsInQ' />

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
<ReactPlayer url='https://www.youtube.com/watch?v=ysz5S6PUM-U' />

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.

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

PropDescriptionDefault
urlThe url of a video or song to play  Can be an array or MediaStream object
playingSet to true or false to pause or play the mediafalse
loopSet to true or false to loop the mediafalse
controlsSet to true or false to display native player controls.  For Vimeo videos, hiding controls must be enabled by the video owner.false
lightSet to true to show just the video thumbnail, which loads the full player on click  Pass in an image URL to override the preview imagefalse
volumeSet the volume of the player, between 0 and 1  null uses default volume on all players #357null
mutedMutes the player  Only works if volume is setfalse
playbackRateSet the playback rate of the player  Only supported by YouTube, Wistia, and file paths1
widthSet the width of the player640px
heightSet the height of the player360px
styleAdd inline styles to the root element{}
progressIntervalThe time between onProgress callbacks, in milliseconds1000
playsinlineApplies the playsinline attribute where supportedfalse
pipSet to true or false to enable or disable picture-in-picture mode  Only available when playing file URLs in certain browsersfalse
stopOnUnmountIf you are using pip you may want to use stopOnUnmount={false} to continue playing in picture-in-picture mode even after ReactPlayer unmountstrue
fallbackElement or component to use as a fallback if you are using lazy loadingnull
wrapperElement or component to use as the container elementdiv
playIconElement or component to use as the play icon in light mode
previewTabIndexSet the tab index to be used on light mode0
configOverride options for the various players, see config prop

Callback props

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

PropDescription
onReadyCalled when media is loaded and ready to play. If playing is set to true, media will play immediately
onStartCalled when media starts playing
onPlayCalled when media starts or resumes playing after pausing or buffering
onProgressCallback 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 }
onDurationCallback containing duration of the media, in seconds
onPauseCalled when media is paused
onBufferCalled when media starts buffering
onBufferEndCalled when media has finished buffering  Works for files, YouTube and Facebook
onSeekCalled when media seeks with seconds parameter
onPlaybackRateChangeCalled when playback rate of the player changed  Only supported by YouTube, Vimeo (if enabled), Wistia, and file paths
onPlaybackQualityChangeCalled when playback quality of the player changed  Only supported by YouTube (if enabled)
onEndedCalled when media finishes playing  Does not fire when loop is set to true
onErrorCalled when an error occurs whilst attempting to play media
onClickPreviewCalled when user clicks the light mode preview
onEnablePIPCalled when picture-in-picture mode is enabled
onDisablePIPCalled when picture-in-picture mode is disabled

Config prop

There is a single config prop to override settings for each type of player:

<ReactPlayer
  url={url}
  config={{
    youtube: {
      playerVars: { showinfo: 1 }
    },
    facebook: {
      appId: '12345'
    }
  }}
/>

Settings for each player live under different keys:

KeyOptions
youtubeplayerVars: Override the default player varsembedOptions: Override the default embed optionsonUnstarted: Called when state changes to unstarted (usually when video fails to autoplay)
facebookappId: Your own Facebook app IDversion: Facebook SDK versionplayerId: Override player ID for consistent server-side rendering (use with react-uid)attributes: Extra data attributes to pass to the fb-video element
soundcloudoptions: Override the default player options
vimeoplayerOptions: Override the default paramstitle: Set the player iframe title attribute
muxattributes: Apply element attributesversion: Mux player version
wistiaoptions: Override the default player optionsplayerId: Override player ID for consistent server-side rendering (use with react-uid)
mixcloudoptions: Override the default player options
dailymotionparams: Override the default player vars
twitchoptions: Override the default player optionsplayerId: Override player ID for consistent server-side rendering (use with react-uid)
fileattributes: Apply element attributesforceVideo: Always render a <video> elementforceAudio: Always render an <audio> elementforceHLS: Use hls.js for HLS streamsforceSafariHLS: Use hls.js for HLS streams, even on SafariforceDisableHLS: Disable usage hls.js for HLS streamsforceDASH: Always use dash.js for DASH streamsforceFLV: Always use flv.jshlsOptions: Override the default hls.js optionshlsVersion: Override the hls.js version loaded from jsdelivr, default: 0.13.1dashVersion: Override the dash.js version loaded from cdnjs, default: 2.9.2flvVersion: Override the flv.js version loaded from jsdelivr, default: 1.5.0

Methods

Static Methods

MethodDescription
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 attempting 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.

MethodDescription
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 <video> 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.

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.

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 (
      <div className='player-wrapper'>
        <ReactPlayer
          className='react-player'
          url='https://www.youtube.com/watch?v=ysz5S6PUM-U'
          width='100%'
          height='100%'
        />
      </div>
    )
  }
}
.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 <script src='/path/hls.js'></script> 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:

<script src='https://cdn.jsdelivr.net/npm/react-player/dist/ReactPlayer.standalone.js'></script>
<script>
  const container = document.getElementById('container')
  const url = 'https://www.youtube.com/watch?v=d46Azg3Pm4c'

  renderReactPlayer(container, { url, playing: true })

  function pausePlayer () {
    renderReactPlayer(container, { url, playing: false })
  }
</script>

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 <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).

Multiple Sources and Tracks

Passing an array of YouTube URLs to the url prop will load them as an untitled playlist.

<ReactPlayer
  url={[
    'https://www.youtube.com/watch?v=oUFJJNQGwhk',
    'https://www.youtube.com/watch?v=jNgP6d9HraI'
  ]}
/>

When playing file paths, an array of sources can be passed to the url prop to render multiple <source> tags.

<ReactPlayer playing url={['foo.webm', 'foo.ogg']} />

You can also specify a type for each source by using objects with src and type properties.

<ReactPlayer
  playing
  url={[
    {src: 'foo.webm', type: 'video/webm'},
    {src: 'foo.ogg', type: 'video/ogg'}
  ]}
/>

<track> elements for subtitles can be added using config.file:

<ReactPlayer
  playing
  url='foo.webm'
  config={{ file: {
    tracks: [
      {kind: 'subtitles', src: 'subs/subtitles.en.vtt', srcLang: 'en', default: true},
      {kind: 'subtitles', src: 'subs/subtitles.ja.vtt', srcLang: 'ja'},
      {kind: 'subtitles', src: 'subs/subtitles.de.vtt', srcLang: 'de'}
    ]
  }}}
/>

Migrating to 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.

Supported media

Contributing

See the contribution guidelines before creating a pull request.

Thanks

@beskar-labs/gravity@lwtears/admin-common@plurall/reader@contiago/toolbar@globalsoftba/bede-starterkit@blaze-cms/react-page-builder@codecademy/gamut@corva/ui@liquiditeam/editorbullseye-storiesresource-center@storycopter/gatsby-starter-storycoptervideo-clipvideo-clip-lapi-connect-test-package@tffg/emn-lib-componentstest-clipxy-video-clipgatsby-theme-evelangatsby-theme-sanity-evelanplayer-reactdevelapp-regional-frontendtraffic_2018_bgutraffic_bgu_2018globalchampions-component-libraryglobalchampions-components-librarydcg-direct-purchaseriver-sharingwebhelp-templateadmiral_storybook@techstars/coredsavelyevstuff-ui2d8e-appquantic-ui42dd8860-c724chunk-file-upload-withprogresschunkfilepploadcultgearchattingappreact-annotation-tool-cloneextramarks-rj-videoplayervideo-cliperlyrahealth-uicoretest-theme-shawacademymbfjs@decooda_inc/media-carouselslash-common-components@epignosis_llc/gnosis1teespace-drive-appteespace-admin@tbiz/tb-componentsaidexa-open-dsbeedeez-webapp-progatsby-theme-providencecom.sap.designsystem.communitysimple-antd-management-fast-frameworksid-npm-test3sid-npmtest-1sid-npmtest-2sid-test-create-npm@tipzty/tipzty-react-lib@creaditor/cdtr-text-editor@mcxbr/catalog@mcxbr/livereact-simple-music-player@digi-edu/dynamic-lesson-contenthelanique-transcriptdoc4k_react_ui@fishbot/prismic@elwood-studio/distribute-react@botpress/channel-messenger@infinitebrahmanuniverse/nolb-react-pl@thequack/shareddraftjs-editor-byloopsdraftjs-editor-loops@brandingbrand/fsengagement@sds-stream/library@openchannel/react-common-componentsreact-fb-image-grid-2support-worksuiteelementary-editorlexical-lib-demoluck-design-testintraactive-sdk-uipro-gallerycomponents-bullseye@everything-registry/sub-chunk-2603caseark-uicrc-ui-1tourstream-mhb-liblighthouse-reactlinkfield@geppettoengine/geppetto-clientl-min-componentshighstep-presentationhieu-test-001homey-presentationhttpeace-page-editorhyper-hitachi
2.15.1

26 days ago

2.15.0

29 days ago

2.14.1

3 months ago

2.14.0

3 months ago

2.14.0-canary.0

5 months ago

2.13.0

7 months ago

2.11.1

1 year ago

2.11.2

1 year ago

2.12.0

1 year ago

2.11.0

2 years ago

2.10.1

2 years ago

2.10.0

2 years ago

2.9.0

3 years ago

2.8.2

3 years ago

2.8.1

3 years ago

2.8.0

3 years ago

2.7.2

3 years ago

2.7.1

3 years ago

2.7.0

3 years ago

2.6.2

4 years ago

2.6.1

4 years ago

2.6.0

4 years ago

2.4.0

4 years ago

2.5.0

4 years ago

2.3.1

4 years ago

2.3.0

4 years ago

2.2.0

4 years ago

2.2.0-beta.2

4 years ago

2.2.0-beta.1

4 years ago

2.2.0-beta.0

4 years ago

2.1.1

4 years ago

2.1.0

4 years ago

2.0.2-beta.0

4 years ago

2.0.1

4 years ago

2.0.0

4 years ago

2.0.0-alpha.1

4 years ago

1.15.3

4 years ago

1.15.2

4 years ago

1.15.1

4 years ago

1.15.0

4 years ago

2.0.0-alpha.0

4 years ago

1.14.2

4 years ago

1.14.1

4 years ago

1.14.0

4 years ago

1.13.0

5 years ago

1.12.0

5 years ago

1.11.2

5 years ago

1.11.1

5 years ago

1.11.0

5 years ago

1.10.0

5 years ago

1.9.3

5 years ago

1.9.2

5 years ago

1.9.1

5 years ago

1.9.0

5 years ago

1.8.0

5 years ago

1.7.1

5 years ago

1.7.0

5 years ago

1.6.6

6 years ago

1.6.5

6 years ago

1.6.4

6 years ago

1.6.3

6 years ago

1.6.2

6 years ago

1.6.1

6 years ago

1.6.0

6 years ago

1.5.1

6 years ago

1.5.0

6 years ago

1.4.0

6 years ago

1.3.2

6 years ago

1.3.1

6 years ago

1.3.0

6 years ago

1.2.1

6 years ago

1.2.0

6 years ago

1.1.3

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.0

6 years ago

1.0.0-beta.7

6 years ago

1.0.0-beta.6

6 years ago

1.0.0-beta.5

6 years ago

1.0.0-beta.4

6 years ago

1.0.0-beta.3

6 years ago

1.0.0-beta.2

6 years ago

1.0.0-beta.1

6 years ago

1.0.0-beta.0

6 years ago

0.25.3

6 years ago

0.25.2

6 years ago

0.25.1

6 years ago

0.25.0

6 years ago

0.24.6

7 years ago

0.24.5

7 years ago

0.24.4

7 years ago

0.24.3

7 years ago

0.24.2

7 years ago

0.24.1

7 years ago

0.24.0

7 years ago

0.23.0

7 years ago

0.22.0

7 years ago

0.21.0

7 years ago

0.20.0

7 years ago

0.19.1

7 years ago

0.19.0

7 years ago

0.18.0

7 years ago

0.17.2

7 years ago

0.17.1

7 years ago

0.17.0

7 years ago

0.16.0

7 years ago

0.15.0

7 years ago

0.14.3

7 years ago

0.14.2

7 years ago

0.14.1

7 years ago

0.14.0

7 years ago

0.13.0

7 years ago

0.12.1

7 years ago

0.12.0

7 years ago

0.11.0

8 years ago

0.10.0

8 years ago

0.9.0

8 years ago

0.8.0

8 years ago

0.7.5

8 years ago

0.7.4

8 years ago

0.7.3

8 years ago

0.7.2

8 years ago

0.7.1

8 years ago

0.7.0

8 years ago

0.6.0

8 years ago

0.5.8

8 years ago

0.5.7

8 years ago

0.5.6

8 years ago

0.5.5

8 years ago

0.5.4

8 years ago

0.5.3

8 years ago

0.5.2

8 years ago

0.5.1

8 years ago

0.5.0

8 years ago

0.4.2

8 years ago

0.4.1

8 years ago

0.4.0

8 years ago

0.3.7

8 years ago

0.3.6

8 years ago

0.3.5

8 years ago

0.3.4

8 years ago

0.3.3

8 years ago

0.3.2

8 years ago

0.3.1

8 years ago

0.3.0

8 years ago

0.2.1

8 years ago

0.2.0

8 years ago

0.1.0

8 years ago

0.0.8

9 years ago

0.0.7

9 years ago

0.0.6

9 years ago

0.0.5

9 years ago

0.0.4

9 years ago

0.0.3

9 years ago

0.0.2

9 years ago

0.0.1

9 years ago