{"id":11826,"library":"react-player","title":"ReactPlayer","description":"ReactPlayer is a highly versatile React component designed for embedding and controlling various media sources directly within a web application. It supports a wide array of popular platforms, including YouTube, Vimeo, Wistia, TikTok, Spotify, and Twitch, as well as generic file paths, HLS, and DASH streams. The current stable version is 3.4.0. The library underwent a significant architectural rewrite in v3, transitioning to TypeScript and enhancing its modularity. Maintenance has been officially taken over by Mux, indicating a commitment to more frequent updates and fixes, ensuring its adaptability to evolving media platforms and web standards. Its key differentiators include broad support for numerous media providers and the ability to dynamically load players, which helps reduce initial bundle size when code splitting is enabled.","status":"active","version":"3.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/cookpete/react-player","tags":["javascript","react","media","player","video","audio","youtube","vimeo","wistia","typescript"],"install":[{"cmd":"npm install react-player","lang":"bash","label":"npm"},{"cmd":"yarn add react-player","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-player","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency for any React component.","package":"react","optional":false},{"reason":"Core peer dependency for rendering React components to the DOM.","package":"react-dom","optional":false},{"reason":"Required for TypeScript users to ensure type compatibility with React.","package":"@types/react","optional":true}],"imports":[{"note":"This is the primary way to import the component. CommonJS `require` is not directly supported for default exports.","wrong":"const ReactPlayer = require('react-player')","symbol":"ReactPlayer","correct":"import ReactPlayer from 'react-player'"},{"note":"Use this import for dynamic, code-split loading of players, reducing initial bundle size. Your build system must support `import()` statements.","symbol":"ReactPlayer (Lazy Loading)","correct":"import ReactPlayer from 'react-player/lazy'"},{"note":"Import the type definition for the component's props for use in TypeScript projects.","wrong":"import { PlayerProps } from 'react-player'","symbol":"ReactPlayerProps","correct":"import { ReactPlayerProps } from 'react-player'"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport ReactPlayer from 'react-player';\n\nfunction MyVideoPlayer() {\n const [playing, setPlaying] = useState(false);\n const [volume, setVolume] = useState(0.8);\n const [muted, setMuted] = useState(false);\n\n return (\n
\n );\n}\n\nexport default MyVideoPlayer;\n","lang":"typescript","description":"Demonstrates a basic ReactPlayer setup with playback controls, volume adjustment, and mute functionality for a YouTube video."},"warnings":[{"fix":"Refer to the official migration guide for `react-player` when upgrading from v2 to v3 to understand necessary code changes and prop adjustments.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always use the `url` prop to pass the media source to `ReactPlayer`, e.g., ``.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'play')"},{"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`.","cause":"The `url` prop was either not provided or evaluated to `undefined` when the `ReactPlayer` component was rendered.","error":"Warning: Failed prop type: The prop `url` is marked as required in `ReactPlayer`, but its value is `undefined`."},{"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.","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.","error":"DOMException: play() failed because the user didn't interact with the document first."},{"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.","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.","error":"ReferenceError: ReactPlayer is not defined"}],"ecosystem":"npm"}