How to Add and Customize Video Headers in WordPress

WordPress 4.7 introduced the concept of video headers built right into the core software. This visual element is nothing new – we’ve seen it on countless sites and themes – but building it into core makes it considerably more approachable than before.

According to WordPress.org:

In this post, I’ll walk you through how to use the new video header feature, complete with styling and customizations.

Displaying a Basic Video Header

A new tag, the_custom_header_markup(), was introduced in WordPress 4.7. It unifies the display of header images and header videos in one easy step. It displays a div that contains the header image and enqueues the script necessary for the video.

By default the header image is shown. If the user’s environment supports video, the image will be progressively enhanced to display the video instead.

To display a video header you need to do two things: add theme support for videos and use the the_custom_header_markup() wherever you want the header to show up.

To add theme support use the following snippet:

Setting Display Locations

By default, videos are only loaded on the front page of your WordPress website. Themes may want to override this behavior. Luckily there are multiple ways to get it done.

The is_header_video_active filter

When WordPress decides whether or not to display a video, it looks at a value passed through the is_header_video_active() filter. If the value is true it displays the video, otherwise it does not. The code below will extend the video to all single pages, not just the home page.

The video-active-callback header parameter

When registering theme support for videos we can use the video-active-callback parameter to modify the default conditions that determine when a video is shown. By default, it is set to is_front_page. This means that WordPress will display a header video when the is_front_page() function returns true: on the front page. You can use a different built-in WordPress function or write your own:

The function above will display the video header for guests only, on all pages except the home page.

Setting Display Conditions

As well as controlling which pages videos are shown on, you might also want to restrict videos to certain viewport sizes. By default, videos are only shown on displays that are at least 900px wide and 500px tall.

The header_video_settings filter allows you to change these values (and a couple of other settings). The code below modifies the viewport conditions for displaying videos:

Modifying Text

The same header_video_settings filter can be used to modify the text of various elements. See the example below for all available options:

Modifying Styles

Elements are unstyled by default, so it is a theme’s job to make things look nice. A div with the class wp-custom-header is created whenever a video or an image is available. The div will contain one or the other, depending on the conditions set.

Play and pause buttons can also be styled. They are regular button elements, as can be seen in the code snippet below:

Customizing Your Video Headers in WordPress

Videos should be used sparingly, but can make a huge difference when used right. The new video header feature makes it extremely easy for themes to implement it without needing to worry about the UI.

Check out the feature announcement for more information and be sure to let us know if you’ve created some great video headers!