Migration Guide

This guide provides instructions for migrating between major versions of ReactPlayer.

Migrating to v3.0

Breaking changes are in bold and on fire 🔥.

Some player providers are not supported yet

Since v3.0 is a new architecture not all providers have been updated. It is recommended to keep using v2 and vote to add this provider to v3 in discussions. These include:

  • Dailymotion
  • SoundCloud
  • Streamable
  • Twitch
  • Facebook
  • Mixcloud
  • Kaltura

Lazy players

As of v3.0 all the players are lazy loaded by default. Due to the use of lazy and Suspense, 🔥 React 16.6 or later is now required.

Player props

As of v3.0 some player props are renamed to be closer to the native HTMLMediaElement naming.

  • 🔥 url => src
  • 🔥 playsinline => playsInline
  • 🔥 progressInterval deprecated
  • 🔥 stopOnUnmount deprecated
  • 🔥 wrapper is undefined by default. Set to div if you want a wrapper element.

Player instance methods

As of v3.0 use ref to call instance methods on the player. See the demo app for an example of this. Since v3, the instance methods aim to be 🔥 compatible with the HTMLMediaElement interface.

Player callback props

As of v3.0 some player callback props are renamed to be closer to the native HTMLMediaElement event naming.

  • 🔥 onProgress => onTimeUpdate and onProgress
  • 🔥 onDuration => onDurationChange
  • 🔥 onPlaybackRateChange => onRateChange
  • 🔥 onSeek => onSeeking and onSeeked
  • 🔥 onBuffer => onWaiting
  • 🔥 onBufferEnd => onPlaying
  • 🔥 onEnablePIP => onEnterPictureInPicture
  • 🔥 onDisablePIP => onLeavePictureInPicture

Migrating to v2.0

Breaking changes are in bold and on fire 🔥.

Lazy players

As of v2.2, 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.

Due to the use of lazy and Suspense, 🔥 React 16.6 or later is now required.

// Before
import ReactPlayer from 'react-player'

// After
import ReactPlayer from 'react-player/lazy'

Lazy players were the default import in v2.1, but moved to react-player/lazy in v2.2 to avoid causing problems with common build systems.

Single player imports

As of v2.2, the 🔥 location of single player imports has changed. Single players are not available in v2.0 and v2.1.

// Before
import ReactPlayer from 'react-player/lib/players/YouTube'

// After
import ReactPlayer from 'react-player/youtube'

Preloading

The preload config option was originally added to solve a very specific use case a very long time ago. Modern browsers are trending towards disabling autoplay by default, which makes the preload behaviour quite useless. The implementation was also quite hacky, and added to the bundle size for a feature that seems to be very rarely used. For this reason, 🔥 the preload option has been removed.

The config prop

🔥 Deprecated config props have been removed. Previously these props still worked, but with a console warning.

// Before
<ReactPlayer 
  youtubeConfig={{ playerVars: { showinfo: 1 } }} 
/>

// After
<ReactPlayer 
  config={{ youtube: { playerVars: { showinfo: 1 } }}} 
/>

It is also worth noting that you no longer need to use separate config keys for different players. For example, if you are only ever using one type of url you can put player-specific options directly inside config.

// Before
<ReactPlayer 
  youtubeConfig={{ playerVars: { showinfo: 1 } }} 
/>

// After
<ReactPlayer 
  config={{ playerVars: { showinfo: 1 } }} 
/>

onReady is invoked with the player instance

Previously, instance methods would be called using refs. They still can, but in v2.0, onReady is called with the ReactPlayer instance, giving you the option of storing the instance and calling methods on it. This is especially useful when using getInternalPlayer.

// Before
class Player extends Component {
  ref = player => {
    this.player = player            // Store a player that may not be ready for methods
    this.player.getInternalPlayer() // Returns null if player is not ready
  }
  handleReady = () => {
    this.player.getInternalPlayer() // Internal player now ready
  }
  render () {
    return (
      <ReactPlayer ref={this.ref} onReady={this.handleReady} />
    )
  }
}

// After
class Player extends Component {
  handleReady = player => {
    this.player = player            // Store a player that is ready for methods
    this.player.getInternalPlayer() // Internal player now ready
  }
  render () {
    return (
      <ReactPlayer onReady={this.handleReady} />
    )
  }
}