plyr-react

The <Plyr /> component is the simplest way to integrate a media player. You must import the plyr-react/plyr.css stylesheet to apply the default theme.

Important CSS Path Change: As of v5.0.0, use plyr-react/plyr.css. For older versions (v4), use plyr-react/dist/plyr.css.

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 <Plyr {...plyrProps} />
}

You can control the player instance programmatically by using a React ref. The ref.current.plyr object provides direct access to the underlying Plyr instance, allowing you to call methods like .play(), .pause(), or .fullscreen.enter().

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 (
    <div>
      <Plyr
        ref={ref}
        source={{
          type: "video",
          sources: [{ src: "/path/to/video.mp4", type: "video/mp4" }],
        }}
      />
      <button onClick={playVideo}>Play</button>
      <button onClick={enterFullscreen}>Go Fullscreen</button>
    </div>
  )
}

The Plyr component is a React wrapper around the Plyr media player. It renders a <video> element with the plyr-react plyr classes applied.

To use it, provide a source (media source information) and optional options (Plyr configuration). You can also pass standard HTML video attributes (like controls, muted, etc.) directly to the component.

To interact with the player instance from a parent component, use a ref with the type APITypes, which provides access to the underlying plyr instance.

import { Plyr } from 'plyr-react';

function MyPlayer() {
  const playerRef = React.useRef<APITypes>(null);

  // Access the player instance via playerRef.current.plyr
  const handlePlay = () => {
    playerRef.current?.plyr.play();
  };

  return (
    <Plyr
      ref={playerRef}
      source={{
        type: 'video',
        sources: [
          {
            src: 'https://cdn.plyr.io/static/demo/View_From_A_Blue_Moon_Trailer-720p.mp4',
            type: 'video/mp4',
          },
        ],
      }}
      options={{...
    />
  );
}

The usePlyr hook manages the lifecycle of a Plyr instance (instantiation, reconfiguration, and destruction) for a given video element.

It is designed to be used when you need manual control over the video element's ref while still exposing the Plyr API to a forwarded ref.

Parameters:

• ref: A Ref<APITypes> that will receive the API object { plyr: PlyrInstance }.
• params: A PlyrConfigurationProps object containing source and options.
• deps (optional): A DependencyList. If not provided, the hook re-runs when params.options or params.source change.

Returns:

• A React.Ref<HTMLVideoElement> that must be attached to the <video> element.

import { usePlyr, type APITypes } from 'plyr-react';

function CustomPlayer() {
  const apiRef = React.useRef<APITypes>(null);
  const videoRef = React.useRef<HTMLVideoElement>(null);

  const playerParams = {
    source: { type: 'video', sources: [{ src: '...', type: 'video/mp4' }] },
    options: { ... }
  };

  // Connect the lifecycle to the video element
  const elementRef = usePlyr(apiRef, playerParams);

  return <video ref={elementRef} className="plyr" />;
}