Skip to content
Get packs

Guide · Open source

How to use Plyr: install, set up HTML5, YouTube and Vimeo players

Updated · written with AI from the project's own documentation and checked against our catalogue data

Plyr is an open-source JavaScript library that replaces the default look of web video and audio players with a cleaner, customizable set of controls. It works with standard HTML5 media elements as well as embedded YouTube and Vimeo players. This guide shows you how to install it, add the markup, and start a player on a page. Plyr is deprecated: its maintainers recommend Video.js 10 for new projects, so this guide is most useful if you maintain an existing Plyr site.

Plyrsampotts/plyr · ★ 30k · MIT

Quick start

  1. 1Decide if Plyr fits. Plyr is deprecated and receives security updates only. Use it for existing sites and Video.js 10 for new projects.
  2. 2Install from npm. Run npm i plyr in your project folder to add the library.
  3. 3Add the markup. Place a video or audio element, or a YouTube or Vimeo embed container, with an id such as player on the page.
  4. 4Include the CSS. Add plyr.css to your head with a link tag.
  5. 5Load the JavaScript. Import Plyr as an ES6 module or load plyr.js before the closing body tag.
  6. 6Create the player. Run new Plyr('#player') to turn the element into a Plyr player.
  7. 7Test in a modern browser. The library supports modern browsers, so test your page in those and check captions and playback.

Check whether Plyr is the right choice

Plyr is deprecated and only receives security updates. The project's README says to use Video.js 10 for new projects, and it links a migration guide for Plyr users.

Plyr is a good fit if you already have a site using it, or if you need one consistent player across HTML5, YouTube and Vimeo sources. It is a library, not a ready-made video app, so it has to be embedded in a web page.

  • Existing Plyr site: keep it working and apply security updates.
  • New project: the README recommends Video.js 10 instead.
  • Non-developer looking for a finished video app: Plyr will not fit, because it must be built into a page.

Install Plyr with npm

If your project uses a build system, install Plyr from npm and import it as an ES6 module. The source lists no prerequisites for installation.

To build from source instead, the README gives the command below, which installs dependencies and writes a build to the dist folder.

npm i plyr # Build from source npm i && npm run build

Add the player markup to your page

Plyr extends the standard HTML5 media element, so for HTML5 video and audio you use normal video and audio tags. Set the poster with data-poster, which avoids downloading the image twice. Captions are optional and use a WebVTT track file.

For YouTube and Vimeo, you can progressively enhance an iframe embed, or use an empty div with data-plyr-provider and data-plyr-embed-id. The plyr__video-embed class makes the embed responsive.

  • Add playsinline and controls to the video element.
  • Use data-poster for the poster image.
  • Add a track element with kind="captions" for VTT captions.
<video id="player" playsinline controls data-poster="/path/to/poster.jpg"> <source src="/path/to/video.mp4" type="video/mp4" /> <source src="/path/to/video.webm" type="video/webm" /> <!-- Captions are optional --> <track kind="captions" label="English captions" src="/path/to/captions.vtt" srclang="en" default /> </video>

Create a YouTube or Vimeo player

For YouTube, the origin parameter should match the domain hosting the embed, or you can omit it. The README notes that autoplay, loop, hl (YouTube only) and playsinline (YouTube only) query parameters are set as config options automatically.

For Vimeo, the same approach applies. Use the iframe method or the div method shown in the README.

<div id="player" data-plyr-provider="youtube" data-plyr-embed-id="bTqVqk7FSmY"></div> <div id="player" data-plyr-provider="vimeo" data-plyr-embed-id="76979871"></div>

Load the JavaScript and CSS

Include the stylesheet in your head, then either import Plyr as a module or load the script before the closing body tag. The README says the CDN is provided by Cloudflare. It also offers a polyfilled build, but recommends managing polyfills separately in your application.

If you do not use a build system, you can self-host the pre-built files, download them from the CDN, or get them from unpkg.

  • plyr.css: include in the head.
  • plyr.js: import as a module or load before </body>.
  • plyr.polyfilled.js: CDN build with polyfills included.
<link rel="stylesheet" href="path/to/plyr.css" /> <script src="path/to/plyr.js"></script> <script> const player = new Plyr('#player'); </script>

Use the API and events

Plyr provides a standardized API to toggle playback, control volume, seek and more. Events are also standardized across HTML5, YouTube and Vimeo, so you do not need to use the Vimeo or YouTube APIs directly.

The README also lists features such as keyboard shortcuts, picture-in-picture, speed controls, multiple caption tracks, preview thumbnails and i18n support for controls. Check the Plyr documentation at plyr.io for the full API and options.

  • Keyboard shortcuts are supported.
  • Picture-in-picture is supported.
  • Multiple caption tracks are supported.
  • Streaming playback is supported through hls.js, Shaka and dash.js examples.

What people use it for

  • Keep an existing website's video player working with security updates.
  • Show the same player controls for self-hosted HTML5 video and YouTube or Vimeo embeds.
  • Add captions in WebVTT format to a video on a marketing or course page.
  • Add a lightweight audio player with HTML5 audio sources to a blog or podcast page.

Frequently asked questions

Is Plyr free to use?

Plyr is released under the MIT licence, as listed in the project details. Check the licence file in the repository for the full terms.

Is Plyr still maintained?

Plyr is deprecated and only receives security updates. The README recommends Video.js 10 for new projects.

What are the alternatives to Plyr?

The project lists Video.js, Vidstack, Media Chrome and hls.js as comparable projects. The README recommends Video.js 10 as the replacement for new work.

Does Plyr work with YouTube and Vimeo?

Yes. Plyr supports YouTube and Vimeo embeds alongside HTML5 media, and it standardizes events across all three formats.

Do I need a framework to use Plyr?

No. The README says Plyr is written in vanilla ES6 JavaScript and requires no jQuery or framework.

How do I install Plyr?

Run npm i plyr to install from npm, or run npm i && npm run build to build from source.

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

Plyr suits developers who already run it and want one simple, accessible player across HTML5, YouTube and Vimeo. For new projects, the README recommends Video.js 10, because Plyr is deprecated and only gets security fixes. Non-developers looking for a finished video app should choose something else.

Install options & downloads