react-player

What is react-player?

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.

What are react-player's main functionalities?

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' />

Other packages similar to react-player

video-react

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.

react-video-js-player

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.

react-h5-audio-player

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.

README

ReactPlayer

A React component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia and DailyMotion. Not using React? No problem.

Migrating to 1.0.0

All existing implementations of ReactPlayer should still work without any changes after migrating. The major changes are to how the component works internally. Keep an eye out for bugs and raise an issue if one doesn’t already exist.

Usage

npm install react-player --save
# or
yarn add react-player

import React, { Component } from 'react'
import ReactPlayer from 'react-player'

class App extends Component {
  render () {
    return <ReactPlayer url='https://www.youtube.com/watch?v=ysz5S6PUM-U' playing />
  }
}

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 like Meteor 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.

Props

Prop	Description	Default
url	The url of a video or song to play
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 Note: Vimeo, Twitch and Wistia player controls are not configurable and will always display	false
volume	Sets the volume of the appropriate player	0.8
muted	Mutes the player	false
playbackRate	Sets the playback rate of the appropriate player Note: Only supported by YouTube, Wistia, and file paths	1
width	Sets the width of the player	640px
height	Sets 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
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
onSeek	Called when media seeks with seconds parameter
onEnded	Called when media finishes playing
onError	Called when an error occurs whilst attempting to play media

Config prop

As of version 0.24, there is a single config prop to override the settings for the various players. If you are migrating from an earlier version, you must move all the old config props inside config:

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

The old style config props still work but will produce a console warning:

<ReactPlayer
  url={url}
  youtubeConfig={{ playerVars: { showinfo: 1 } }}
  facebookConfig={{ appId: '12345' }}
/>

Settings for each player live under different keys:

Key	Options
youtube	playerVars: Override the default player vars preload: Used for preloading
facebook	appId: Your own Facebook app ID
soundcloud	options: Override the default player options preload: Used for preloading
vimeo	playerOptions: Override the default params preload: Used for preloading
wistia	options: Override the default player options
dailymotion	params: Override the default player vars preload: Used for preloading
file	attributes: Apply element attributes forceAudio: Always render an <audio> element forceHLS: Use hls.js for HLS streams forceDASH: Always use dash.js for DASH streams hlsOptions: Override the default hls.js options

Preloading

When preload is set to true for players that support it, a short, silent video is played in the background when ReactPlayer first mounts. This fixes a bug where videos would not play when loaded in a background browser tab.

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.

Instance Methods

Use ref to call instance methods on the player. See the demo app for an example of this.

Method	Description
seekTo(amount)	Seek to the given number of seconds, or fraction if amount is between 0 and 1
getCurrentTime()	Returns the number of seconds that has been played   ◦  Returns null if duration is unavailable
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

Advanced Usage

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

Standalone player

If you aren’t using React, you can still render a player using the standalone library:

<script src='https://cdn.rawgit.com/CookPete/react-player/standalone/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

Using Bower

bower install react-player --save

<script src='bower_components/react/react.js'></script>
<script src='bower_components/react/react-dom.js'></script>
<script src='bower_components/react-player/dist/ReactPlayer.js'></script>
<script>
  ReactDOM.render(
    <ReactPlayer url='https://www.youtube.com/watch?v=d46Azg3Pm4c' playing />,
    document.getElementById('container')
  )
</script>

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

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

<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'}
    ]
  }}}
/>

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
• Supported file types are playing using <video> or <audio> 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

• Many thanks to Kostya Luchankin for help overhauling the player inheritance patterns.
• Thanks to anyone who has contributed.

Changelog

v1.1.3

21 February 2018

• Match YouTube URL with extra parameters #332
• Update mp3 example #330
• Update stored config when props change #329
• Pass through all source props when using array of objects #333
• Skip wistia tests 6e536d1
• Fix soundcloud canPlay test 1f158d1