A simple Web Component for Ionic to have a fullscreen background video playing
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Built With Stencil

Ionic Background Video Web Component

This is a very simple Web Component for Ionic 4 applications to have a fullscreen video playing in the background of a page.

Why make a Web component?

Turns out there are many tweaks to do to make it work perfectly, like we need for a clean and profesionnal app. So I figured I would save you the trouble.


The video will not play correctly on iOS 9 and less. it was not supported yet: https://webkit.org/blog/6784/new-video-policies-for-ios/

This component is designed to play a video that is already on the device.

How to use it with you Ionic App

I actually made an article on our blog explaining how to do that: https://geeklearning.io/how-to-create-a-reusable-web-component-with-stenciljs-and-use-it-in-your-ionic-4-application/

For more information about importing it in your app, refer to the Stencil documentation: https://stenciljs.com/docs/angular

Manual modifications


First, you have to allow inline media playback in your Cordova config.xml, otherwise it will not work on iOS :

<preference name="AllowInlineMediaPlayback" value="true" />


You don't want your ion-content to scroll at all on this page, so you need to set it's force-overscroll attribute to false:

<ion-content force-overscroll="false">
  <gl-background-video src="assets/your_video.mp4" poster="assets/your_video_screen.png"></gl-background-video>

Install with npm

Install this Web Component with NPM:

npm install --save gl-ionic-background-video

Import it

Import it in the module of the page which will use it (home.module.ts for example):

import 'gl-ionic-background-video';

Include the Custom Element Schema

You also need to tell your page's module to allow non-angular elements. Add the CUSTOM_ELEMENTS_SCHEMA to the list of schemas of you module:

  imports: [
        path: '',
        component: HomePage
  declarations: [HomePage],
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // here is the schema declaration to add
export class HomePageModule {}

Call defineCustomElements

Call the defineCustomElements function from the Stencil component collection in your main.ts like this:

import { defineCustomElements } from 'gl-ionic-background-video/dist/loader'; // add this line

  .catch(err => console.log(err)); // This is already in main.ts, it's just to show you where to put everything.
defineCustomElements(window); // call the function here


This Web Components accepts 3 parameters :

  • The video source : src
  • The fallback image : poster
  • The mute state of the video : muted