Plyr React

plyr-react logo

A responsive media player that is simple, easy to use, and customizable for video, audio, YouTube, and Vimeo.

You can see a live demo here.

> Make sure to select the version for the plyr-react in the dependencies.

$3

Plyr-React is a responsive, accessible, and highly customizable media player component for React. It wraps the popular Plyr media player, providing a simple and powerful way to integrate video, audio, YouTube, and Vimeo content into your React applications.

The library is designed for modern development, featuring a tree-shakeable and side-effect-free build, ensuring optimal performance. It offers both a simple component for quick setup and an advanced hook for complex, custom integrations.

#### Key Features

- Broad Media Support: Natively supports HTML5 and , as well as embedded players from YouTube and Vimeo.
- Deep Customization: A rich set of options allows you to control every aspect of the player's UI and behavior, including controls, settings menus, and event listeners.
- Accessibility Focused: Built on the accessible foundation of the underlying Plyr player.
- Modern React API: Offers a simple component for easy use and a powerful usePlyr hook for full control and custom logic.
- Full Programmatic Access: Provides direct access to the Plyr instance via React refs, allowing you to control playback, volume, fullscreen, and more from your application code.
- TypeScript Support: Fully typed for a superior developer experience, with exported types for props, options, and the player instance.
- Streaming Support: Can be integrated with streaming libraries like HLS.js for adaptive bitrate streaming.

---

$3

You can install plyr-react using NPM, Yarn, or PNPM.

``bash

`NPM`


npm install plyr-react
Yarn

yarn add plyr-react
PNPM

pnpm add plyr-react


_(Note: PNPM instructions have been added for completeness as they were not present in the original documentation.)_
---
$3

For plyr-react to function correctly, it requires you to install some packages in your project yourself. These are known as peer dependencies. The package.json file specifies the following:

- react: Version 16.8or newer. -plyr: Version 3.7.7 or a compatible version.

You must ensure these are listed in your project's package.json. Most package managers will warn you if these are missing.

To install peer dependencies:

`bash

`NPM`


npm install react react-dom plyr
Yarn

yarn add react react-dom plyr
PNPM

pnpm add react react-dom plyr


---
$3

- Node.js: Version 16or higher. - React: Version16.8 or higher.

---

`$3`

#### 1. Basic Usage: The Component

For most use cases, the component is the simplest way to get started. Remember to import the stylesheet to apply the default player theme.

`tsx import Plyr from "plyr-react" import "plyr-react/plyr.css"

// Player source configuration const plyrProps = { source: { type: "video", sources: [ { src: "https://cdn.plyr.io/static/demo/View_From_A_Blue_Moon_Trailer-720p.mp4", type: "video/mp4", size: 720, }, ], poster: "https://cdn.plyr.io/static/demo/View_From_A_Blue_Moon_Trailer-HD.jpg", }, options: { // Full list of options: https://github.com/sampotts/plyr#options controls: [ "play-large", "play", "progress", "current-time", "mute", "volume", "captions", "settings", "pip", "airplay", "fullscreen", ], }, }

function MyPlayer() { return }`

> Important CSS Path Change: > As of v5.0.0, the CSS import path isplyr-react/plyr.css. For older versions (v4), you must use plyr-react/dist/plyr.css.

#### 2. Advanced Usage: The usePlyr Hook

For full control over the player's lifecycle and integration, the usePlyr hook is the recommended approach. It allows you to build a completely custom component wrapper.

`jsx import React from "react" import { usePlyr } from "plyr-react" import "plyr-react/plyr.css"

// This example re-creates the component using the hook const CustomPlyr = React.forwardRef((props, ref) => { const { source, options = null, ...rest } = props

// usePlyr returns a ref that you can attach to a

 element.
  const raptorRef = usePlyr(ref, {
    source,
    options,
  })

return `

#### 3. Accessing the Player API via Refs

You can control the player instance programmatically by using a ref. The ref gives you access to the full Plyr API. The ref's current object will contain a plyr property, which is the player instance.

`tsx import React, { useRef, useEffect } from "react" import Plyr from "plyr-react" import "plyr-react/plyr.css"

const PlayerController = () => { const ref = useRef(null)

const playVideo = () => { // ref.current.plyr is the Plyr instance if (ref.current && ref.current.plyr) { ref.current.plyr.play() } }

const enterFullscreen = () => { if (ref.current && ref.current.plyr) { ref.current.plyr.fullscreen.enter() } }

return (


              ref={ref}
        source={{
          type: "video",
          sources: [{ src: "/path/to/video.mp4", type: "video/mp4" }],
        }}
      />

)
}


Example
> You can fork these examples
**Javascript
example:** 

**Typescript
example:** 

**Basic HLS
integration** 
Codesandbox
> Check out the examples directory for the useHls integration guide.

`jsx ref={usePlyr(ref, { ...useHls(hlsSource, options), source, })} className="plyr-react plyr" />`

Demo: https://react-fpmwns.stackblitz.io

`Nightly version of plyr-react:`

`Contribute`

We are open to all new contribution, feel free to read CONTRIBUTING and CODE OF CONDUCT section, make new issue to discuss about the problem ![Gitter](https://gitter.im/plyr-react/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge), and improve/fix/enhance the source code with your PRs. There is a ready to code Gitpod, you can jump into it from