Vue Plyr Video and Audio Player

Common errors

• TypeError: Cannot read properties of undefined (reading 'use')

  cause Attempting to use `Vue.use()` for global component registration in a Vue 3 application, where `Vue` is no longer a global constructor.
  fix For Vue 3, use the application instance's `use` method: `createApp(App).use(VuePlyr).mount('#app')`.

• Player displays with incorrect styling, missing controls, or is unformatted.

  cause The essential CSS stylesheet for `vue-plyr` has not been loaded into the application.
  fix Add `import 'vue-plyr/dist/vue-plyr.css'` to your application's entry point (e.g., `main.js`, `main.ts`).

• ReferenceError: window is not defined (during SSR build or development)

  cause The default `vue-plyr` module attempts to access browser-specific APIs (like `window` or `document`) during the server-side rendering phase.
  fix Import the SSR-optimized version of the component: `import VuePlyr from 'vue-plyr/dist/vue-plyr.ssr.js'` in your SSR-specific files or use dynamic imports for client-only components.

Warnings

• breaking Version 7.x primarily targets Vue 3.x. While Vue 2.x support is maintained, the global registration syntax has changed from `Vue.use()` to `createApp().use()` for Vue 3 applications.
  Fix: For Vue 3.x, use `createApp(App).use(VuePlyr, { plyr: {} }).mount('#app')`. For Vue 2.x, continue using `Vue.use(VuePlyr, { plyr: {} })`.
• gotcha Forgetting to import the required CSS stylesheet (`vue-plyr/dist/vue-plyr.css`) will result in an unstyled or visually broken player, as the component only provides functionality.
  Fix: Ensure `import 'vue-plyr/dist/vue-plyr.css'` is included in your main application entry file (e.g., `main.js` or `main.ts`).
• gotcha When developing Server-Side Rendered (SSR) applications (e.g., with Nuxt.js), the standard client-side build of `vue-plyr` may cause build errors due to direct browser API access. An SSR-optimized module is available.
  Fix: Import the SSR-specific build: `import VuePlyr from 'vue-plyr/dist/vue-plyr.ssr.js'`. Refer to the package's SSR documentation for detailed Nuxt.js integration.
• gotcha To interact with the underlying Plyr.js player instance (e.g., to call methods like `play()`, `pause()`), you must use a `ref` on the `vue-plyr` component and access its `player` property.
  Fix: Add a ref to your component `<vue-plyr ref="plyrRef">` and then access `this.$refs.plyrRef.player` in your component's methods or lifecycle hooks.

Install

• npm install vue-plyr npm
• yarn add vue-plyr yarn
• pnpm add vue-plyr pnpm

Imports

• VuePlyr
  wrong:

  const VuePlyr = require('vue-plyr')

  correct:

  import VuePlyr from 'vue-plyr'

  Use named import for the component. CommonJS require is generally deprecated in modern Vue CLI/Vite projects favoring ESM.
• CSS
  wrong:

  import 'vue-plyr/css'

  correct:

  import 'vue-plyr/dist/vue-plyr.css'

  The CSS is provided as a direct file path and must be explicitly imported for player styling.
• VuePlyr SSR
  wrong:

  import VuePlyr from 'vue-plyr'

  correct:

  import VuePlyr from 'vue-plyr/dist/vue-plyr.ssr.js'

  For Server-Side Rendering (SSR) environments, this specific build must be used to avoid client-side API errors.

Quickstart

Initializes a Vue 3 application, globally registers the `VuePlyr` component with default options, and demonstrates embedding an HTML5 video player.

import { createApp } from 'vue'
import App from './App.vue'
import VuePlyr from 'vue-plyr'
import 'vue-plyr/dist/vue-plyr.css'

const app = createApp(App)

app.use(VuePlyr, { plyr: {} })

app.mount('#app')

// In App.vue or another component:
// <template>
//   <vue-plyr :options="{autoplay: false, muted: false}">
//     <video controls crossorigin playsinline>
//       <source src="https://cdn.plyr.io/static/demo/View_From_A_Blue_Moon_Trailer-576p.mp4" type="video/mp4" />
//     </video>
//   </vue-plyr>
// </template>
// <script>
// export default {
//   name: 'App'
// }
// </script>