vue-lazy-youtube-video
1.x documentation can be found here.
Features
- reduces initial load size by ~1.1MB per video
- built with a11y in mind – fully accessible via keyboard and to screen readers
.webpthumbnail format for modern browsers that support it, with.jpgfallback for browsers that don't- fully customizable through
propsandslots
Installation
Via NPM
$ npm install vue-lazy-youtube-video --save
Via Yarn
$ yarn add vue-lazy-youtube-video
Directly in browser
<script src="https://cdn.jsdelivr.net/npm/vue"></script>
<!-- Styles with CSS Custom Properties -->
<link rel="stylesheet" href="https://unpkg.com/vue-lazy-youtube-video/dist/style.css"></link>
<!-- Minified styles with CSS Custom Properties -->
<!-- <link rel="stylesheet" href="https://unpkg.com/vue-lazy-youtube-video/dist/style.min.css"></link> -->
<!-- Styles without CSS Custom Properties -->
<!-- <link rel="stylesheet" href="https://unpkg.com/vue-lazy-youtube-video/dist/style.simplified.css"></link> -->
<!-- Minified styles without CSS Custom Properties -->
<!-- <link rel="stylesheet" href="https://unpkg.com/vue-lazy-youtube-video/dist/style.simplified.min.css"></link> -->
<script src="https://unpkg.com/vue-lazy-youtube-video"></script>
<script>
// as a plugin
Vue.use(VueLazyYoutubeVideo.Plugin)
// as a component
Vue.use('LazyYoutubeVideo', VueLazyYoutubeVideo.default)
</script>
Initialization
Styles
import 'vue-lazy-youtube-video/dist/style.css'
As a global component
⚠️ It must be called beforenew Vue().
import Vue from 'vue'
import LazyYoutubeVideo from 'vue-lazy-youtube-video'
Vue.component('LazyYoutubeVideo', LazyYoutubeVideo)
As a local component
import LazyYoutubeVideo from 'vue-lazy-youtube-video'
export default {
name: 'YourAwesomeComponent',
components: {
LazyYoutubeVideo,
},
}
As a plugin
⚠️ It must be called beforenew Vue().
import Vue from 'vue'
import { Plugin } from 'vue-lazy-youtube-video'
Vue.use(Plugin)
Usage
<template>
<LazyYoutubeVideo src="https://www.youtube.com/embed/4JS70KB9GS0" />
</template>
Demo
API
Properties
The list of available props (with their types, default values and descriptions) is listed below:
| Property | Required | Type | Default | Description |
|---|---|---|---|---|
src |
true |
string |
<iframe />'s src attribute in https://www.youtube.com/embed/[VIDEO_ID] format. URL can contain any query part, but notice that autoplay=1 is always appended |
|
alt |
false |
string |
Video thumbnail |
Value of the alt attribute of the thumbnail <img /> element |
buttonLabel |
false |
string |
Play video |
Value of the aria-label attribute of the play <button></button> element. Improves a11y |
aspectRatio |
false |
string |
16:9 |
Aspect ratio of the video. This prop helps to save proportions of the video on different container sizes. Should match the number:number pattern |
previewImageSize |
false |
string |
maxresdefault |
Size of the thumbnail, generated by YouTube. Available variants: default, mqdefault, sddefault, hqdefault, maxresdefault. More info |
thumbnail |
false |
{ webp: string, jpg: string} |
Custom thumbnail object, which should contain two keys: webp and jpg. Value of the key is the path to the custom thumbnail image |
|
iframeAttributes |
false |
object |
{ allowfullscreen: true, frameborder: 0, allow: 'accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture' } |
Custom attributes that will be assigned to the <iframe /> element |
webp |
false |
boolean |
true |
Whether or not try to load .webp thumbnail in favor of .jpg. Note that old videos may not have generated .webp thumbnail |
autoplay |
false |
boolean |
false |
Whether or not to play video as soon as component mounts into the DOM |
thumbnailListeners |
false |
Record<string, Function | Function[]> |
Listeners that will be attached to the preview thumbnail | |
enablejsapi |
false |
boolean |
false |
Include 'enablejapi=1' parameter to the generated src attribute of the <iframe /> element. This will allow you to listen to the init:player event as well as access the YT.Player instance via the getPlayerInstance method. Make sure you have injected the proper YouTube <script /> tag or passed the injectPlayerScript prop |
playerOptions |
false |
Partial<YT.PlayerOptions> |
{} |
Options the will be passed to the YT.Player constructor |
injectPlayerScript |
false |
boolean |
false |
Will auto inject the proper YouTube <script /> when enablejapi is passed and there is no window.YT.Player |
parameters |
false |
YT.Parameters |
{} |
YouTube Parameters that will be injected into the generated <iframe /> src attribute |
Events
| Name | Payload | Description |
|---|---|---|
'load:iframe' |
{ iframe?: HTMLIFrameElement } |
Happens when native' <iframe /> element load event fires |
'init:player' |
{ instance: YT.Player } |
Happens when the YT.Player instance is instantiated |
Methods
| Name | Type | Description |
|---|---|---|
getPlayerInstance |
() => Nullable<YT.Plater> |
Returns an instance of the YT.Player when the enablejapi prop is passed and the YT.Player is initialized (check 'init:player' event), in other cases returns null |
Slots
Component provides some slots.
The list of available slots is listed below:
| Slot | Description |
|---|---|
button |
Slot gives an ability to provide custom play button |
icon |
Slot gives an ability to provide custom icon of the play button |
⚠️ Note, that whenbuttonslot is passed and this slot contains<button></button>, ones should not to forget to addaria-label(if this button contains only icon) andtype="button"attributes. Also, if that button do not contain.y-video-buttonclass, all default styles will be lost, so style concerns it's up to developer.
FAQ
Question: How to play/pause/stop a video?
Answer: Pass the enablejapi prop and then listen to 'init:player' event to get an instance of the YT.Player. All the available instance methods you can find here. Hint: You can also get a player instance via the getPlayerInstance method.
Code
<LazyYoutubeVideo
ref="youtube"
src="..."
enablejsapi
@init:player="onPlayerInit"
/>
import { InitPlayerEventPayload } from 'vue-lazy-youtube-video'
{
// ...
methods: {
onPlayerInit(payload: InitPlayerEventPayload) {
console.log(payload.instance)
console.log(this.$refs.youtube.getPlayerInstance())
},
},
// ...
}
Tests
You can run unit tests by running the next command:
npm run test
Unit
Jest is used for unit-tests.
Jest and VueTestUtils is used for unit tests.
You can run unit tests by running the next command:
npm run test:unit
TypeScript support
Component is completely built and tested using TypeScript.
Here is the list of the types you can use:
// import type {} TypeScript 3.8 +
import {
Props,
LoadIframeEventPayload,
InitPlayerEventPayload,
Thumbnail,
} from 'vue-lazy-youtube-video'
Development
- Clone this repository
- Install dependencies using
yarn installornpm install - Start development server using
npm run devscript
Build
To build the production ready bundle simply run npm run build:
After the successful build the following files will be generated in the dist folder:
├── vue-lazy-youtube-video.common.js
├── vue-lazy-youtube-video.esm.js
├── vue-lazy-youtube-video.js
├── vue-lazy-youtube-video.min.js
├── style.css
├── style.min.css
├── style.simplified.css
├── style.simplified.min.css
Powered by
VueRollup(and plugins)BabelJestVue Test UtilsTypeScriptPostCSS
Inspiration
Inspired by Vadim Makeev. Vadim created a comprehensive tutorial in which he shows how to lazyload YouTube videos properly.
56 Sep 9, 2022
12 Dec 26, 2022
7.8k Dec 29, 2022
107 Nov 16, 2022
31 Nov 18, 2020
37 Nov 14, 2022
9 Mar 31, 2022
0 Mar 29, 2020
0 Mar 19, 2021
7 Jun 1, 2022
0 Oct 21, 2021
57 Dec 22, 2022
67 Nov 24, 2022
711 Dec 9, 2022
26 Mar 9, 2022
252 Nov 21, 2022
25 Aug 11, 2021
99 Oct 27, 2022
91 Nov 18, 2021