Guide · Open source
How to use react-player: install, play videos and handle events
Updated · written with AI from the project's own documentation and checked against our catalogue data
react-player is a React component that takes a single URL and loads the right player for it, whether that is YouTube, Vimeo, Twitch or a plain media file. This guide shows you how to install it, render a player, control playback with props, listen to events and add custom controls. You need a React project and npm or yarn.
ReactPlayercookpete/react-player · ★ 10.3k · MIT Install options & downloads Quick start
- 1Install the package. Run npm install react-player in your React project.
- 2Import the component. Import ReactPlayer from 'react-player' in the file where you want the video.
- 3Pass a URL. Set the src prop to a YouTube, Vimeo or file URL.
- 4Set playback props. Use playing, loop, volume or muted to control playback. Set muted to true if you want autoplay.
- 5Handle events. Add callback props such as onPlay, onProgress or onEnded to react to what the player does.
- 6Optionally add custom controls. Use controls for native controls, or pair the player with Media Chrome for custom ones.
Install react-player in your React project
Add the package to your project with npm. The README also lists yarn as an option.
You need Node.js and npm or yarn, plus a React project. react-player is a React component, so it will not run outside a React app.
npm install react-playerRender your first video player
Import ReactPlayer and pass a video address to the src prop. The component works out which player to load from the URL and loads the scripts it needs.
If your build system supports import() and code splitting, you can enable it to lazy load the player for the src you pass in. The README notes this adds several reactPlayer chunks to your output but reduces the main bundle size.
import React from 'react'
import ReactPlayer from 'react-player'
// Render a YouTube video player
<ReactPlayer src='https://www.youtube.com/watch?v=LXb3EKWsInQ' />Control playback and listen to events
Use props to control playback. The playing prop set to true or false plays or pauses the media, and loop, volume, muted and playbackRate adjust how it plays. Width and height default to 320px and 180px.
Callback props fire on player events. Common ones are onPlay, onPause, onProgress, onTimeUpdate, onEnded and onError. onEnded does not fire when loop is true.
Autoplay needs care: as of Chrome 66, videos must be muted to play automatically, so set muted={true} for autoplay. Some players such as Facebook cannot be unmuted until the user interacts with the video, so enable controls so users can unmute themselves.
- src: the URL of a video or song to play
- playing: true or false to play or pause
- controls: show native player controls (hiding Vimeo controls must be enabled by the video owner)
- onReady: fires when media is loaded; if playing is true, media plays immediately
- onError: fires when an error occurs while attempting to play
Use light mode for click-to-load thumbnails
Set the light prop to true to show only the video thumbnail. The full player loads when the user clicks. Pass an image URL to light to override the preview image.
Use onClickPreview to respond when a user clicks the light mode preview, and previewTabIndex to set its tab index.
Configure individual players with the config prop
The single config prop overrides settings for each player type. Settings live under the keys youtube, vimeo and hls. Each key links to that service's own options list in the README, for example YouTube player parameters or hls.js fine-tuning.
<ReactPlayer
src={src}
config={{
youtube: {
color: 'white',
},
}}
/>Add custom controls with Media Chrome
By default react-player is chromeless. Set controls to true to show native controls, which look different for each player. For your own controls, the README suggests Media Chrome, a library of UI components for building custom media controls. A simple example is linked in the README as a CodeSandbox.
<ReactPlayer src='https://www.youtube.com/watch?v=LXb3EKWsInQ' controls />What people use it for
- Embed YouTube and Vimeo videos in a React site behind one component.
- Show a thumbnail on a page and load the full player only when a visitor clicks it (light mode).
- Track watch progress by using onProgress and onTimeUpdate.
- Play a background audio or video file through a plain HTML5 source.
- Build a custom control bar with Media Chrome.
Frequently asked questions
How do I install react-player?
Run npm install react-player in your project. The README also shows yarn add react-player as an alternative. You need Node.js, npm or yarn, and React.
Is react-player free to use?
The project is licensed under MIT, an open-source licence. Check the LICENSE file in the repository for the full terms.
Which services does react-player support?
The README lists file paths, HLS, DASH, YouTube, Vimeo, Wistia and Mux in its description. The package description also names Facebook, Twitch, SoundCloud, Streamable and DailyMotion. Some players have restrictions, such as Vimeo controls that the video owner must enable.
Why does my video not autoplay?
As of Chrome 66, videos must be muted to play automatically. The README says to set muted={true}. Some players like Facebook cannot be unmuted until the user interacts with the video.
Is react-player still maintained?
The README says maintenance is being taken over by Mux, and that ReactPlayer will remain open source with a higher rate of fixes and releases over time. The README also says v3 is not backwards compatible with v2, so check the migration guide if you are upgrading.
What are alternatives to react-player?
The source lists video.js, Plyr, Vidstack and react-youtube as comparable projects. react-youtube is focused on YouTube, while react-player covers several services behind one component.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use react-player if you are building a React web app and need one component to play videos from YouTube, Vimeo and other services, with playback props and events. Pick something else if you are not using React, or if you need a guaranteed long-term maintainer under the original author, or if you need v2 compatibility without a migration.
Install options & downloads