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

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=ysz5S6PUM-U' />

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=ysz5S6PUM-U' />

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

Callback props

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

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:

Methods

Static Methods

Instance Methods

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

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://unpkg.com/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'}
    ]
  }}}
/>

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

• Thanks to anyone who has contributed.
• Big thanks to my Patreon supporters!

Jackson Doherty

Joseph Fung