Plyr: HTML5, YouTube and Vimeo Player
Plyr does one job well: it swaps the native HTML5, YouTube, and Vimeo controls for a single skinnable UI with one standardized JavaScript API across all three. Plyr doesn't decode HLS or DASH itself, so you still wire up hls.js or dash.js and hand Plyr the resulting element — but once that's done, the same events and API calls work everywhere.
What is Plyr?
Plyr is a JavaScript library that wraps native HTML5 video and audio elements, plus YouTube and Vimeo iframe embeds, in one consistent, accessible player UI. It's written in vanilla ES6 with no jQuery dependency, ships CSS you restyle through CSS custom properties, and layers on VTT caption support, keyboard shortcuts, and picture-in-picture.
Core features
- ✓Plays HTML5 video and audio plus YouTube and Vimeo embeds through the same wrapper, so you don't juggle three separate embed APIs.
- ✓Ships full VTT caption support, including multiple caption tracks, plus screen-reader-friendly markup.
- ✓Uses real HTML elements for controls — an `<input type="range">` for volume, a `<progress>` element for the scrubber, `<button>`s for buttons — instead of div-based click hacks.
- ✓Exposes a standardized API for playback, volume, and seeking, and fires the same events regardless of whether the source is HTML5, YouTube, or Vimeo.
- ✓Supports native fullscreen with a fallback to a 'full window' mode when the browser won't cooperate.
- ✓Adds picture-in-picture, keyboard shortcuts, adjustable playback speed, and the playsinline attribute for inline mobile playback.
- ✓Restyles entirely through CSS custom properties like `--plyr-color-main`, instead of requiring a rebuild of the stylesheet.
- ✓Supports streaming playback through hls.js, Shaka, and dash.js integrations, plus i18n for translating the control labels.
What you can build with Plyr
- •Embedding a self-hosted HTML5 video with captions and a branded control bar.
- •Standardizing playback controls across a page that mixes native video, YouTube, and Vimeo embeds.
- •Building an audio player for a podcast or radio site using the `<audio>` support.
- •Adding an HLS or DASH stream where Plyr handles the UI while hls.js or dash.js handles the actual decoding.
Adding Plyr to your project
Plyr installs three ways, and the README documents all three: pull in the `plyr` package and `import Plyr from 'plyr'` as an ES6 module; drop in `plyr.js` and `plyr.css` from Cloudflare's CDN — the README's example points at `https://cdn.plyr.io/3.8.4/plyr.js`, so check the CDN for the current build — choosing the polyfilled build (`plyr.polyfilled.js`) if you need older-browser support; or self-host the pre-built files from unpkg, or run `npm i && npm run build` to produce your own `dist` output. The SVG icon sprite loads from the same CDN automatically unless you point it elsewhere.
Basic setup for HTML5, YouTube, and Vimeo
For native HTML5 video, Plyr just needs standard markup: a `<video>` element with a `data-poster` attribute (not `poster`, so the image isn't fetched twice) and a `<track kind="captions">` for subtitles — no extra HTML required. Audio works the same way with a plain `<audio controls>` element. For YouTube and Vimeo, you progressively enhance an existing `<iframe>` embed, or use a bare `<div>` with `data-plyr-provider` and `data-plyr-embed-id` attributes if you'd rather not embed the iframe yourself. Once the markup is in place, `const player = new Plyr('#player');` turns it into a Plyr instance, and the `plyr__video-embed` class keeps YouTube and Vimeo embeds responsive at a 16:9 ratio.
Why developers choose Plyr
- ✓One API and one set of events for HTML5, YouTube, and Vimeo, so switching a page from self-hosted video to a YouTube embed doesn't mean rewriting your JS.
- ✓Real semantic controls (range input, progress element, buttons) instead of the usual div-soup video-player markup.
- ✓CSS custom properties make restyling the whole player a token change, not a stylesheet rewrite.
- ✓MIT licensed, so it's free to use in commercial projects without a separate license purchase.
- ✓No jQuery or framework dependency — it's plain ES6, so it doesn't drag in a runtime you didn't already have.
Known limitations
- △Plyr doesn't decode HLS or DASH streams itself — you still need hls.js, Shaka, or dash.js in the page, and Plyr just controls the resulting element.
- △YouTube and Vimeo are the providers Plyr documents; there's no built-in support for other video hosts.
- △The ads feature is tied to a specific partner (vi.ai) — for a different monetization vendor you're setting `ads.tagUrl` yourself rather than using a documented integration.
- △The CSS custom-property list is long, and finding the one variable that controls a specific detail, like the tooltip arrow size, means reading the reference table, not guessing.
Alternatives to consider
Frequently asked questions
Plyr is released under the MIT license, which permits commercial use without a separate license fee, as long as you keep the license notice in the source.
Plyr does not require jQuery — the README describes it as written in vanilla ES6 JavaScript with no framework dependency, so adding Plyr doesn't pull jQuery into a project that doesn't already use it.
Plyr styling is customized through CSS custom properties like `--plyr-color-main` for the primary UI color and `--plyr-video-control-color` for control icons, so restyling means overriding these variables rather than editing Plyr's stylesheet directly.
Plyr supports HLS and DASH playback by integrating with hls.js, Shaka, and dash.js — Plyr itself provides the controls and UI, while those libraries handle decoding the streaming manifest.
Plyr's README states it supports modern browsers and links out to its own browser-support documentation rather than listing version numbers; older browsers are covered by using the polyfilled CDN build instead of the standard one.
Plyr's README doesn't document React or Vue-specific integration — it ships as a vanilla ES6 module you initialize with `new Plyr('#player')`, so using it inside React or Vue means wrapping that initialization in the framework's own lifecycle hooks.
The problem it solves
Native HTML5 video controls look different in every browser, and YouTube and Vimeo iframe embeds each ship their own separate JavaScript API with their own events, so a page mixing all three ends up with three different control styles and three different ways to listen for something like 'played' or 'ended'. Plyr collapses that into one markup pattern and one event API.
Who should try it — and who should skip
Try Plyr if you're hand-rolling `<video>` markup or fighting inconsistent YouTube and Vimeo embed styling across a site — the standardized API alone saves rewriting event handlers per provider. Skip it if you need HLS/DASH decoding out of the box, since you'll still be adding hls.js or dash.js yourself, or if the project already ships Video.js plugins you'd have to rebuild.
Related repositories
Is plyr worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of plyr.
