Vue3 Ytframe

A fully-typed Vue 3 wrapper around the YouTube Iframe API.

npm version npm downloads Vue 3 TypeScript types included

## Features - ๐Ÿงฉ Single component that wraps the **entire** YouTube Iframe API (all methods & events) - ๐ŸŸฆ **Ships TypeScript types** โ€” typed props, events, and the player instance - ๐Ÿชถ Zero runtime dependencies beyond Vue 3 itself - โณ Promise-based API loading, so the player is created only once YouTube is ready - โ™ป๏ธ Automatically destroys the player on unmount (no leaks) - ๐Ÿ“ฆ Ships ESM **and** CommonJS builds (Node SSR / `require()` friendly) ## Installation ```bash npm install vue3-ytframe # or: pnpm add vue3-ytframe / yarn add vue3-ytframe ``` Requires `vue` `^3.5` as a peer dependency. ## Usage ### Option A โ€” register globally (plugin) ```ts import { createApp } from "vue" import VueYtframe from "vue3-ytframe" import App from "./App.vue" createApp(App).use(VueYtframe).mount("#app") ``` ### Option B โ€” register locally (named export) ```vue ``` ### Controlling the player with a template ref ```vue ``` ## Props | Prop | Type | Default | Description | |--------------|-------------------|-----------|----------------------------------------------------------| | `videoId` | `string` | `null` | YouTube video ID. One of `videoId`/`videoUrl` required. | | `videoUrl` | `string` | `null` | Full YouTube URL (parsed to an ID internally). | | `width` | `number \| string`| `"100%"` | Player width. | | `height` | `number \| string`| `"100%"` | Player height. | | `playerVars` | `object` | `{}` | [YouTube player parameters](https://developers.google.com/youtube/player_parameters). | ## Events `ready`, `playing`, `paused`, `ended`, `stateChange`, `playbackQualityChange`, `playbackRateChange`, `error`, `apiChange` โ€” each emits the underlying `YT.Player`. See the [Events docs](https://kiranparajuli589.github.io/vue3-ytframe/#/docs/ref=events). ## Methods The full Iframe API surface is exposed on the component instance (`playVideo`, `pauseVideo`, `seekTo`, `mute`, `setVolume`, `loadVideoById`, โ€ฆ). The pure helper `getVideoIdFromYoutubeURL(url)` is also exported standalone. See the [Methods docs](https://kiranparajuli589.github.io/vue3-ytframe/#/docs/ref=methods). > Player methods throw a clear error if called before the `ready` event โ€” wait > for `ready` (or check the exposed `player` ref) before driving playback. ## SSR (Nuxt, Quasar, etc.) `vue3-ytframe` ships a `.cjs` build, so Node SSR servers can `require()` it without `ERR_REQUIRE_ESM`. The player itself uses the browser YouTube Iframe API (`document`, `window`), so render it **client-only** (e.g. Quasar's `QNoSsr`, Nuxt's ``). ## Links - ๐Ÿ“– [Documentation](https://kiranparajuli589.github.io/vue3-ytframe/#/docs/ref=) - ๐ŸŽ›๏ธ [Playground](https://kiranparajuli589.github.io/vue3-ytframe/#/playground) - ๐Ÿงช [Usage examples](https://kiranparajuli589.github.io/vue3-ytframe/#/docs/ref=examples) - ๐Ÿ“ [Changelog](./CHANGELOG.md) ## Contributing ```bash pnpm install # install deps pnpm dev # run the docs/playground site pnpm test # run the unit tests pnpm typecheck # vue-tsc type checking pnpm lint # eslint pnpm build # build the library + docs ``` Issues and PRs are welcome at the [GitHub repository](https://github.com/kiranparajuli589/vue3-ytframe). ## License [GPL-3.0](./LICENSE) ยฉ Kiran Parajuli