API Reference

This section provides a detailed reference for all props, callbacks, and methods available on the ReactPlayer component.

Props

These props are passed directly to the ReactPlayer component.

  • src: The URL of a video or song to play. Can also be an array of objects with src and type properties for multiple sources.
  • playing: Set to true or false to play or pause the media.
  • preload: Applies the preload attribute where supported.
  • playsInline: Applies the playsInline attribute where supported to prevent fullscreen on iOS.
  • crossOrigin: Applies the crossOrigin attribute where supported.
  • loop: Set to true or false to loop the media.
  • controls: Set to true or false to display native player controls. For Vimeo videos, hiding controls must be enabled by the video owner.
  • volume: Set the volume of the player, between 0 and 1. null (default) uses the player's default volume.
  • muted: Mutes the player when set to true.
  • playbackRate: Set the playback rate of the player (e.g., 1.5 for 1.5x speed). Only supported by YouTube, Wistia, and file paths.
  • pip: Set to true or false to enable or disable Picture-in-Picture mode. Only available for file URLs in certain browsers.
  • width: Set the width of the player (e.g., '640px', '100%'). Defaults to '320px'.
  • height: Set the height of the player (e.g., '360px', '100%'). Defaults to '180px'.
  • style: Add inline styles to the root element.
  • light: Set to true to show just the video thumbnail, which loads the full player on click. Can also be a URL string to a custom thumbnail image, or a React element.
  • fallback: Element or component to use as a fallback while the player is lazy-loading.
  • wrapper: Element or component to use as the container element. Defaults to null (no wrapper).
  • playIcon: Element or component to use as the play icon in light mode.
  • previewTabIndex: Set the tabindex for the light mode preview element. Defaults to 0.
  • previewAriaLabel: Set the aria-label for the light mode preview element.

Callback Props

These props accept a function that will be called on specific player events.

  • onClickPreview(event): Called when the user clicks the light mode preview.
  • onReady(): Called when media is loaded and ready to play.
  • onStart(event): Called when media starts playing for the first time.
  • onPlay(event): Called when the playing prop is set to true or media resumes.
  • onPlaying(event): Called when media actually starts playing after buffering.
  • onProgress(): Called when media data is loaded. Note: for time updates, use onTimeUpdate.
  • onTimeUpdate(event): Called when the media's current time changes.
  • onDurationChange(event): Called when the media's duration is available.
  • onPause(event): Called when media is paused.
  • onWaiting(event): Called when media is buffering and waiting for more data.
  • onSeeking(event): Called when media is seeking.
  • onSeeked(event): Called when media has finished seeking.
  • onRateChange(event): Called when the playback rate changes.
  • onEnded(event): Called when media finishes playing. Does not fire if loop is true.
  • onError(event): Called when an error occurs.
  • onEnterPictureInPicture(event): Called when entering Picture-in-Picture mode.
  • onLeavePictureInPicture(event): Called when leaving Picture-in-Picture mode.

Config Prop

The config prop allows you to pass specific configuration options to the underlying player SDKs.

<ReactPlayer
  src={src}
  config={{
    youtube: {
      color: 'white',
    },
    vimeo: {
      color: 'ffffff'
    },
    hls: {
      // hls.js config options
    }
  }}
/>
Key Options Documentation
youtube Player Parameters
vimeo Embed Options
hls hls.js Config

Instance Methods

To call instance methods, you need to get a reference to the player's underlying DOM element using a ref. The methods aim to be compatible with the standard HTMLMediaElement API.

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

function PlayerComponent() {
  const playerRef = useRef(null);

  const seekForward = () => {
    if (playerRef.current) {
      playerRef.current.currentTime += 10;
    }
  };

  return (
    <>
      <ReactPlayer ref={playerRef} src="..." />
      <button onClick={seekForward}>+10s</button>
    </>
  );
}

Static Methods

These methods are available directly on the ReactPlayer component.

ReactPlayer.canPlay(src)

Determines if a given URL can be played. This checks the URL against a list of supported patterns.

Note: This does not detect media that is unplayable due to privacy settings or streaming permissions. The onError prop will be called in those cases.

if (ReactPlayer.canPlay('https://www.youtube.com/watch?v=dQw4w9WgXcQ')) {
  console.log('This URL can be played!');
}

ReactPlayer.addCustomPlayer(CustomPlayer)

Adds a custom player to the list of available players. See Custom Players for more details.

ReactPlayer.removeCustomPlayers()

Removes all previously added custom players.