Video header WordPress Tutorial

📂 Category: PHP

🖺 Last modified: 8th Dec 2021

🕑 Read Time: 6 min

Video headers can be distinctive and attractive visual enhancements for websites. If used wisely, a short video right on page load can tell quite a story about your website topic. Our Video header WordPress tutorial will show you how to create a custom header with video background for your website. This tutorial is intended for intermediate and experienced WordPress developers comfortable with editing template files, with good knowledge of CSS and understanding PHP code.

Introduction to Video headers in WordPress

WordPress introduced video header support in it’s version 4.7. Video header WordPress support is not available by default, unless you use a WP theme with video header feature. Therefore, if you build a theme from scratch or your current theme does not support video headers by default, you’ll have to activate this feature by adding a couple of functions.

After Video header WordPress support is properly activated, you’ll get the option to choose a header video within the WP Customizer’s Header Media section. WordPress supports .mov and .mp4 video files up to the max. size of 8MB. There’s also the possibility to display a YouTube video as header background.

Before you decide to add a video header to your website, consider the affect of the video on your website loading speed and bandwidth usage. Self hosted .mov and .mp4 can significantly reduce your website loading speed. Furthermore, if yor website is getting a lot of traffic, you could reach your bandwidth limit quite soon. Therefore, we suggest using short videos not longer than 10 seconds and with optimized file size. Even better solution is to use YouTube videos.

Enable Video header WordPress Tutorial

Video headers are nice website visual enhancements. However, be avare on their influence on the website loading speed and optimize the videos accordingly.

Activating the Video header WordPress support

To activate Video header WordPress support all you have to do is add the following code snippet to your theme’s functions.php file.

/* Enable video header support */

add_theme_support( 'custom-header', array(
  'video' => true

You’ll notice a new button in the WP Customizer menu called Header Media. The submenu offers to add a video from the Media Library or paste a YouTube video link. There’s also the option to choose a header background image. It’s a good practice to add a background image as a fallback for browsers that without video header WordPress support.

By enabling video header support and adding the header background video and image, the whole process is not completed yet. Next thing to do is adding a function to the WordPress template that will display the video header.

Displaying the video header inside the WordPress template

To display the video header WordPress introduced a new template tag called the_custom_header_markup(). This template tag generates a <div> element containing an image, video or iframe, depending on what we defined in the Customizer. The best practice is to add the the_custom_header_markup() tag just before the website <header> block.

Open your theme’s header.php file and paste the following code snippet right before the opening <header> tag:

<?php the_custom_header_markup() ?>

By default, the the_custom_header_markup() will display the header video only on the website homepage, and fallback to the predefined background image on other pages or posts. To the header video WordPress will by default also add a Play/Pause button. Some customization of the the_custom_header_markup()default behavior is possible by adding a couple more functions to the theme.

Customizations and tweaks

There are a couple of customizing possibilities for the the_custom_header_markup() tag behavior. Some of the most commonly used options are:

  • displaying the video header only on predefined post types (homepage, pages, posts)
  • enabling or disabling the video header for specific screen resolutions (for example, disabling it for mobile phones)
  • customizing the video control buttons

To customize the header video WordPress doesn’t offer any preferences in the Customizer. The customization is done by adding the_custom_header_markup() related functions to the functions.php file.

Defining the post types to display the header video in WordPress

WordPress will by default display the header video display on the homepage only. On other pages and posts it will fallback to the header image defined in the Customizer. To override this behavior, we have to create a function that filters post types and display the video header only where we define it.

Add the following code snippet to your functions.php file to display the video header on all pages and posts.

function custom_video_header_locations( $active ) {
  if( is_home() || is_page() || is_single() ) {
    return true;

  return false;

Tweak the code to adjust the locations where the video header will be displayed by removing parameters:

  • is_home() displays video header on homepage
  • is_page() displays video header on other pages
  • is_page() displays video header on posts

Defining screen resolutions for displaying the header video

The video header WordPress will by default display only on 900px or higher screen resolutions. Therefore, on mobile devices such as smartphones and tablets the header video won’t be displayed. To save bandwidth, the header image will be displayed instead. This default behavior is possible to customize by creating a filtering function and adding it to the functions.php file.

With the following code snippet, we’ll disable the header video display only on smartphones, assuming that smartphone screen width is not above 420px:

add_filter( 'header_video_settings', 'header_video_resolution');

function header_video_resolution( $settings ) {
  $settings['minWidth'] = 420;
  $settings['minHeight'] = 100;
  return $settings;

Various modifications of this functions are possible. You can also add the $settings[‘maxWidth’] to display the video header only on resolutions below the predefined value. In this case make sure to add a 0 value to the $settings[‘minWidth’] parameter and override the default 900px minimal width. By combining those parameters you can even define a min to max range where you want your video header to be displayed.

Customizing the Play/Pause button

Under the header video WordPress will display a Play/Pause control button. You can change the default button text to anything you like, or for example translate the text to another language. To customize the Play/Pause video control button text, add the following code snippet to your functions.php file and change the text according to your neeeds.

add_filter( 'header_video_settings', 'my_header_video_settings');
function my_header_video_settings( $settings ) {
  $settings['l10n'] = array(
    'pause'      => __( 'Pause video' ),
    'play'       => __( 'Start video' ),
    'pauseSpeak' => __( 'Video paused'),
    'playSpeak'  => __( 'Video playing.'),
  return $settings;

If you wish to hide the Play/Pause button, add the following CSS rule to your theme’s stylesheet:

#wp-custom-header-video-button { display: none; }

We assume you’re familiar with CSS styling and that you’ll have no problems with customizing the visual appearance of the Play/Pause button.

Making the video background responsive

By default, WordPress doesn’t do a great job in making the video header responsive. There’s always some unwanted cropping and the video header height is usually fixed to a certain value. To make the video header responsive, we’ll have to add some custom CSS rules to our stylesheet.

If you’re displaying a self hosted video, this simple set of CSS rules should make the video header responsive in most themes:

#wp-custom-header {
    max-width: 100%;
    overflow: hidden;

#wp-custom-header video {     max-width: 100%; width: 100%; height: auto; }

.html5-video-player .video-click-tracking, .html5-video-player .video-stream { 
    height: auto !important;
    width: 100% !important;

In case you use a YouTube video as your video header, making it perfectly responsive is a bit more complicated. Making YouTube videos perfectly responsive in WordPress is usually not a simple task. It can happen that it will work well in one theme but not in one other. The CSS code bellow will work well in most cases, specially with 16:9 videos. If it doesn’t work well for you or you use a different video format you might need to tweak the code a bit (adjust the padding-bottom value).

.wp-custom-header {
	position: relative;
	padding-bottom: 56.25%;
	padding-top: 30px;
	height: 0;
	overflow: hidden;

.wp-custom-header iframe,  
.wp-custom-header object,  
.wp-custom-header embed {
	position: absolute;
	top: 0;
	left: 0;
	width: 100%;
	height: 100%;

.wp-custom-header iframe, 
.wp-custom-header object, 
.wp-custom-header embed {
        max-width: 100%;

#wp-custom-header-video-button { position: relative; }

Final thoughts on video background in WordPress

Adding a video header to your WordPress site is a useful feature and a nice visual enhancement if done properly. Keep in mind to optimize the size of your header videos to reduce it’s impact on the website loading speed. Using YouTube videos will in most cases make less impact on the loading speed, but sometimes it can cause problems with responsiveness.

If you find this tutorial too advanced or it didn’t work well for you, there are a couple of video header plugins in the WordPress repository you can try out.