Responsive Video Background Player for Vue 2 & 3 ⚡️

!Laravel Tongue

If you are looking to play videos in the background, you've found the right Vue package! 😜 (Heads up: No YouTube videos... yet!)

>Prerequisites: Vue 3.2 or newer for version 2.x of this package. For Vue 2, use version 1.x.

Installation in 2 Steps

1: Add with npm 💻

# For Vue 3.x.x
npm install vue-responsive-video-background-player
For Vue 2.x.x
npm install vue-responsive-video-background-player@1x

2a: Import the component

<script setup>
import VideoBackground from 'vue-responsive-video-background-player';
</script>

Or register it globally:

import { createApp } from 'vue';
import VideoBackground from 'vue-responsive-video-background-player';
const app = createApp(App);
app.component('VideoBackground', VideoBackground);

2b: Install as a plugin

import { createApp } from 'vue';
import { Plugin } from 'vue-responsive-video-background-player';
const app = createApp(App);
app.use(Plugin);

The plugin registers the component as VideoBackground. You can use it as or .

(3: Only for Nuxt users)

Nuxt 3 and Nuxt 4

Since version 2.5.0 the component works with server-side rendering. Create a plugin file, for example plugins/video-background.ts:

import { Plugin } from 'vue-responsive-video-background-player';
export default defineNuxtPlugin((nuxtApp) => {
    nuxtApp.vueApp.use(Plugin);
});

Then use the tag in any page. The server renders the section, the poster, the overlay and your slot content. The server does not know the window width, so the browser adds the video after hydration.

The component injects its CSS with JavaScript. Until the JavaScript runs, the page shows the server HTML without these styles. Since version 2.6.0, add the CSS file to nuxt.config.ts. Then the server HTML has its styles from the start, and the poster shows before the JavaScript runs:

export default defineNuxtConfig({
    css: ['vue-responsive-video-background-player/style.css'],
});

If you prefer to render the component only in the browser, name the plugin file video-background.client.ts and wrap the component in :

<ClientOnly>
    <video-background src="/videos/hero.mp4" style="height: 100vh;" />
</ClientOnly>

A .client plugin alone is not enough: the server cannot resolve the component, and Vue reports a hydration mismatch.

Nuxt 2 (package version 1.x)

Again this is only for Nuxt.js users. Gridsome users click here. At your nuxt.config.js locate the part where you declare your plugins and import the file. Example:

plugins: [
  {
    src: '~/plugins/vue-video-background',
    ssr: false
  }
]

Now the component is globally available and can be used at any .vue file without issues.

TypeScript

Since version 2.5.0 the package contains type declarations for the props, the events, the player methods and the plugin. If you added a declare module 'vue-responsive-video-background-player' file for older versions, you can delete it.

import type { VideoBackgroundSource } from 'vue-responsive-video-background-player';
const sources: VideoBackgroundSource[] = [
    { src: '/videos/mobile.mp4', res: 638, autoplay: true },
];

Usage - (or to make it runnable 🏃‍♂️)

Easiest version 🔍

<video-background 
    src="<your-video-path>.mp4"
    style="max-height: 400px; height: 100vh;"
 >
    <h1 style="color: white;">Hello welcome!</h1>
 </video-background>

Advanced version 🌐

<video-background 
    src="<your-default-video-path>.mp4"
    poster="/images/mainfoto.jpg"
    :sources="[
        {src: '<your-tablet-video-path>.mp4', res: 900, autoplay: true}, 
        {src: '<your-mobile-video-path>.mp4', res: 638, autoplay: true, poster: '<your-mobile-background-image-path>.png'}
    ]"
    style="max-height: 400px; height: 100vh;"
    overlay="linear-gradient(45deg,#2a4ae430,#fb949e6b)" 
>
    <h1 style="color: white;">Hallo welcome!</h1>
</video-background>

Demo ⚡️

https://avidofood.github.io/vue-responsive-video-background-player/

Props

This package is for responsive videos depicting different video resolution. Have you ever visited my favorite car company Tesla? Have a look, they use a lot of video background videos and are using different resolutions for each device.

Props values

• src (required: true)

>Note for Vite and Nuxt: Put the video in the public folder and use the path from the site root, for example src="/videos/hero.mp4". Or import the file, for example import heroVideo from '@/assets/hero.mp4', and bind it with :src="heroVideo". With Vue CLI, bind it like this: `:src="require(@/assets/video/timelapse.mp4)". Read here why

The component sets the type attribute of the video for .mp4, .m4v, .webm, .ogv, .ogg and .m3u8 files. For other URLs, for example a URL without a file extension, it sets no type, and the browser checks the file itself.

>HLS (.m3u8): Safari, iOS and some other browsers play HLS streams natively. For the other browsers, give the component hls.js with the hls prop. See HLS streams.

• poster (default: '')

>Note: The same as for src applies. With Vue CLI, bind the image like this: :poster="require(@/assets/img/logo.png)".

• sources (default: [])

[{src: '.mp4', res: 638, autoplay: true, poster: '.png'}]

To make it work you need at least src, res, autoplay.

poster is optional.

res stand for resolution. This example means that between 0px and 638px of the window's width only the mobile video will be shown. After that your default src.

• autoplay (default: true)

<video-background src="/videos/hero.mp4" transition="slow-fade" />
<style>
.slow-fade-enter-active,
.slow-fade-leave-active {
    transition: opacity 3s;
}
.slow-fade-enter-from,
.slow-fade-leave-to {
    opacity: 0;
}
</style>

<video-background
    src="/videos/hero.mp4"
    poster="/images/hero.jpg"
    pause-button
    respect-reduced-motion
>
    <h1>Hello welcome!</h1>
</video-background>

<video-background class="hero" src="/videos/hero.mp4" pause-button />

.hero .videobg-pause-button {
    top: 16px;
    bottom: auto;
}