Advanced Usage

This guide covers some of the more advanced features of ReactPlayer.

Light Mode

The light prop will render a video thumbnail with a play icon, and only load the full player once a user has interacted with the image. This can significantly improve page load times.

Noembed is used to fetch thumbnails for a video URL. Note that automatic thumbnail fetching for some sources like Facebook, Wistia, and Mixcloud is not supported.

Basic Light Mode

<ReactPlayer src='https://www.youtube.com/watch?v=...' light />

Custom Thumbnail

To use your own thumbnail, pass an image URL to the light prop instead of true.

<ReactPlayer 
  src='https://www.youtube.com/watch?v=...'
  light='https://example.com/my-custom-thumbnail.jpg' 
/>

Custom Preview Element

You can also pass a React element through the light prop for a fully custom preview.

<ReactPlayer light={<img src='https://example.com/thumbnail.png' alt='Thumbnail' />} />

The styles for the default 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

To create a responsive player that maintains its aspect ratio, you can use CSS. Set width and height to 100% on the player and control the size of a wrapper element.

The examples/react/src/App.tsx file demonstrates a modern approach using the aspect-ratio CSS property:

<div className="player-wrapper">
  <ReactPlayer
    className="react-player"
    src={src}
    style={{ width: '100%', height: 'auto', aspectRatio: '16/9' }}
  />
</div>

And the accompanying CSS:

.player-wrapper {
  width: 480px; /* or 100% */
  aspect-ratio: 16 / 9;
  background: rgba(0, 0, 0, .1);
  margin-bottom: 10px;
}

SDK Overrides

You can use your own version of any player SDK by using NPM resolutions (or overrides for npm > 8). For example, to use a specific version of hls.js, add the following to your package.json:

{
  "resolutions": {
    "hls.js": "1.6.2"
  }
}

Multiple Sources and Tracks

Since v3, if the player supports multiple sources or tracks, you can provide them as children, similar to the native <video> or <audio> elements.

<ReactPlayer controls>
  <source src="foo.webm" type="video/webm" />
  <source src="foo.mp4" type="video/mp4" />
  <track kind="subtitles" src="subs/subtitles.en.vtt" srclang="en" default />
  <track kind="subtitles" src="subs/subtitles.ja.vtt" srclang="ja" />
</ReactPlayer>

Mobile Considerations

Due to various platform restrictions, especially on iOS, ReactPlayer is not guaranteed to function perfectly on all mobile devices. For example, many mobile browsers require a direct user interaction (like a tap) to start video playback.

From the YouTube player documentation:

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

To ensure the best compatibility:

• Set playsInline={true} to prevent videos from automatically entering fullscreen on iOS.
• Be aware that autoplay (playing={true}) may not work without being muted={true}.