README

vue-lazy-youtube-video

Vue.js logo plus YouTube logo

1.x documentation can be found here.

vue-lazy-youtube-video
- Features
- Installation
- Initialization
- Usage
- Demo
- API
  - Properties
  - Events
  - Methods
  - Slots
  - FAQ
- Tests
  - Unit
- TypeScript support
- Development
- Build
- Powered by
- Inspiration
- License

Features

reduces initial load size by ~1.1MB per video
built with a11y in mind – fully accessible via keyboard and to screen readers
.webp thumbnail format for modern browsers that support it, with .jpg fallback for browsers that don't
fully customizable through props and slots

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 before new 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 before new 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 when button slot is passed and this slot contains <button></button>, ones should not to forget to add aria-label (if this button contains only icon) and type="button" attributes. Also, if that button do not contain .y-video-button class, 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 install or npm install
Start development server using npm run dev script

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

Inspiration

Inspired by Vadim Makeev. Vadim created a comprehensive tutorial in which he shows how to lazyload YouTube videos properly.

License

MIT

Usage no npm install needed!