ReactPlayer

Common errors

• TypeError: Cannot read properties of undefined (reading 'play')

  cause Attempting to call a method (like `play()`, `seekTo()`) on a `ReactPlayer` ref before the component is fully mounted, the internal player is ready, or after the component has unmounted.
  fix Ensure the ref is assigned and the `onReady` callback has fired before interacting with player methods. Use conditional rendering or an `if (playerRef.current)` check before calling methods.

• Warning: Failed prop type: The prop `url` is marked as required in `ReactPlayer`, but its value is `undefined`.

  cause The `url` prop was either not provided or evaluated to `undefined` when the `ReactPlayer` component was rendered.
  fix Always provide a valid string URL to the `url` prop of `ReactPlayer`. Double-check variable names or conditional logic that might result in an undefined `url`.

• DOMException: play() failed because the user didn't interact with the document first.

  cause The browser's autoplay policy blocked the `play()` action, typically because the video was not muted and there was no prior user interaction with the page.
  fix Set the `muted={true}` prop on `ReactPlayer` to allow autoplay. For unmuted playback, ensure a user interaction (like a click) precedes or triggers the `play()` call.

• ReferenceError: ReactPlayer is not defined

  cause This usually occurs in CommonJS environments when trying to `require('react-player')` and access it directly, or when there's a typo in the import statement.
  fix For CommonJS, use `const ReactPlayer = require('react-player').default;` if using `require`. For ES Modules, ensure the import statement is `import ReactPlayer from 'react-player';` and there are no typos.

Warnings

• breaking Version 3.0.0 introduced a complete rewrite in TypeScript with a new architecture. It is not backwards compatible with v2. Projects upgrading from v2 must consult the migration guide for breaking changes.
  Fix: Refer to the official migration guide for `react-player` when upgrading from v2 to v3 to understand necessary code changes and prop adjustments.
• gotcha Modern browsers (e.g., Chrome 66+) often block autoplay for videos that are not muted or without prior user interaction. Some specific players (like Facebook) may not allow unmuting until a user directly interacts.
  Fix: To enable autoplay, set the `muted={true}` prop on `ReactPlayer`. For unmuting, consider providing native controls (`controls={true}`) or a custom UI element that requires user interaction.
• gotcha When trying to hide controls for Vimeo videos using `controls={false}`, the functionality might be overridden by the video owner's settings on Vimeo. This is not a limitation of ReactPlayer but of Vimeo's platform.
  Fix: Ensure that the Vimeo video's privacy settings allow embedding and control customization. If controls persist, it's an upstream limitation by the video host.
• gotcha The primary prop for specifying the media URL is `url`, not `src`, which might be a common intuition from native HTML5 video elements. Using `src` instead of `url` will prevent the player from loading media.
  Fix: Always use the `url` prop to pass the media source to `ReactPlayer`, e.g., `<ReactPlayer url='https://example.com/video.mp4' />`.

Install

• npm install react-player npm
• yarn add react-player yarn
• pnpm add react-player pnpm

Imports

• ReactPlayer
  wrong:

  const ReactPlayer = require('react-player')

  correct:

  import ReactPlayer from 'react-player'

  This is the primary way to import the component. CommonJS `require` is not directly supported for default exports.
• ReactPlayer (Lazy Loading)

  import ReactPlayer from 'react-player/lazy'

  Use this import for dynamic, code-split loading of players, reducing initial bundle size. Your build system must support `import()` statements.
• ReactPlayerProps
  wrong:

  import { PlayerProps } from 'react-player'

  correct:

  import { ReactPlayerProps } from 'react-player'

  Import the type definition for the component's props for use in TypeScript projects.

Quickstart

Demonstrates a basic ReactPlayer setup with playback controls, volume adjustment, and mute functionality for a YouTube video.

import React, { useState } from 'react';
import ReactPlayer from 'react-player';

function MyVideoPlayer() {
  const [playing, setPlaying] = useState(false);
  const [volume, setVolume] = useState(0.8);
  const [muted, setMuted] = useState(false);

  return (
    <div style={{ width: '640px', height: '360px' }}>
      <h3>Now Playing: ReactPlayer Demo</h3>
      <ReactPlayer
        url='https://www.youtube.com/watch?v=LXb3EKWsInQ'
        playing={playing}
        controls={true}
        volume={volume}
        muted={muted}
        width='100%'
        height='100%'
        onPlay={() => setPlaying(true)}
        onPause={() => setPlaying(false)}
        onVolumeChange={val => setVolume(val)}
      />
      <div style={{ marginTop: '10px' }}>
        <button onClick={() => setPlaying(!playing)}>
          {playing ? 'Pause' : 'Play'}
        </button>
        <button onClick={() => setMuted(!muted)} style={{ marginLeft: '10px' }}>
          {muted ? 'Unmute' : 'Mute'}
        </button>
        <input
          type='range'
          min={0}
          max={1}
          step='any'
          value={volume}
          onChange={e => setVolume(parseFloat(e.target.value))}
          style={{ marginLeft: '10px', width: '100px' }}
        />
        <span>{(volume * 100).toFixed(0)}%</span>
      </div>
    </div>
  );
}

export default MyVideoPlayer;