Video Headers in 4.7

WordPress 4.7 extends the Custom Header feature to introduce support for video.

Video headers are considered decorative elements — like header images, but with motion. With that in mind, they play automatically, loop by default, and don’t have sound. They work best when paired with an image, so they can progressively enhance the experience when video is supported.

Header media UI in the customizer when a theme supports video.

Adding theme support

Adding support for video headers to a theme requires three basic steps:

Registering theme support

Support for video headers can be registered when adding support for custom headers in a theme.

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

Adding support this way does a few things:

  • Renames the “Header Image” customizer section to “Header Media.”
  • Registers customizer controls for selecting a video from the media library or entering a URL to a YouTube video.
  • Enables support for Selective Refresh for header images.

Displaying the header

In previous versions of WordPress, generating the image tag manually was the recommended way to display a header image. WordPress 4.4 introduced the_header_image_tag() to take advantage of the responsive image improvements.

In WordPress 4.7, the_custom_header_markup() unifies support for header images and videos and is the recommended method for displaying custom headers.

It prints a div that will contain a header image if one is set in the customizer and will also enqueue the wp-custom-header.js script if a video is set in the customizer. The script determines if the environment supports video, and if so, it will progressively enhance the header by replacing the image with a video.

Styling the play/pause button

When videos are ready to play, the wp-custom-header.js script inserts a button for pausing and playing the video to help improve accessibility. Core does not apply any CSS to the button in order to make it easier for themes to style. Themes should ensure the button is visible, fits within the design, and add icons if desired.

Pause Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-play">Pause</button>

Play Button
<button type="button" id="wp-custom-header-video-button" class="wp-custom-header-video-button wp-custom-header-video-pause">Play</button>

The text for the button can be modified using the header_video_settings filter.

Styling custom headers

When styling custom headers, it’s important to be aware of the various elements that can be used for header media.

A container div with a wp-custom-header class will always be rendered when a header image or video is available. The div may contain an image, video, or iframe depending on the source of the video, so each of those elements needs to be considered.

The following selectors should be fairly standard for creating responsive headers:

.wp-custom-header iframe,
.wp-custom-header img,
.wp-custom-header video {
	display: block;
	height: auto;
	max-width: 100%;
}

Accessibility considerations

A button to toggle the play/pause state of the video is automatically rendered to help users who may be distracted or disoriented by motion. Voice assistance is also available using wp.a11y.speak, and like the button text, the strings can be modified using the header_video_settings filter.

Bandwidth considerations

To alleviate concerns about bandwidth, videos are only loaded on the front page for viewports that are at least 900 pixels wide and 500 pixels tall. The maximum file size is also capped at 8MB; however, we strongly encourage smaller files be used whenever possible.

Filtering the front page restriction

By default, videos are only loaded on the front page and only the header image is shown on other pages calling the_custom_header_markup(). Themes that need to display the header video on pages other than the front page can:

  • Define a custom callback for the video-active-callback header argument.
  • Use the is_header_video_active filter.

Testing the environment for video support

Themes may also want to customize the criteria used to determine whether or not a video should be embedded. The header_video_settings filter can be used to modify the minimum viewport width and height.

On the front end, the wp.customHeader.supportsVideo() method can be redefined. For instance, it might be desirable to test the user agent to prevent videos from loading on mobile devices that don’t support autoplay. As browsers introduce bandwidth APIs, it may also be worthwhile to disable video on devices with limited bandwidth.

Selective Refresh enabled by default

When registering support for video headers in a theme, header image settings in the customizer are updated to use the postMessage transport to take advantage of the Selective Refresh API introduced in WordPress 4.5. This ensures header images and videos can be updated in the customizer without refreshing the preview window.

If the_custom_header_markup() template tag isn’t being used, themes will need to update the custom header partial to use a custom render_callback, or change the transport for the header_image and header_image_data settings back to refresh.

Creating custom video handlers

Locally hosted mp4 and mov files, as well as YouTube videos, can be used for video headers by default, but it’s possible to add support for additional sources as well.

The wp-custom-header.js script exports a wp.customHeader.handlers global variable that contains a list of video handlers. Each handler accepts information about the current video to determine if it can process it, and if so, it creates the video and inserts it into the DOM.

Core registers two handlers, one for native video, and one for YouTube videos. Each handler extends a base class exposed at wp.customHeader.BaseVideoHandler and implements a basic interface to make sure all videos receive the same level of support.

In the customizer, there is validation to ensure that local videos are a supported format and file size, and that external video links are to YouTube. This validation needs to be filtered to account for custom handlers, either with the customize_validate_external_header_video and customize_validate_header_video filters to filter the core validation functions, or by changing the validation_callback on the header_video and external_header_video customizer settings. See the documentation on customizer validation for more details.

For an example of registering a custom video handler in a plugin, take a look at how this plugin registers support for Vimeo.

New functions and hooks

  • has_header_video() – Checks whether a header video has been set in the customizer.
  • is_header_video_active() – Checks whether a header video is eligible to be shown for the current request.
  • get_header_video_url() – Retrieve the header video URL. May be a local attachment URL or a URL for an external source.
  • the_header_video_url() – Display the header video URL.
  • has_custom_header() – Checks whether a header image or video is set in the customizer and is available for the current request.
  • get_custom_header_markup() – Retrieve the markup for displaying a custom header image (this does not include video support).
  • the_custom_header_markup() – Display the custom header markup and enqueue a script for rendering video in supported environments.

Filters

  • is_header_video_active – Whether a header video should be shown for the current request if available.
  • header_video_settings – Settings that are exported to the wp-custom-header.js script during initial page load and when updating the custom header partial in the customizer preview. The default values are:
    • videoUrl – URL for the selected video.
    • mimeType – MIME type of the selected video.
    • posterUrl – URL for the fallback header image.
    • width – Video width.
    • height – Video height.
    • minWidth – Minimum viewport width to embed a video.
    • minHeight – Minimum viewport height to embed a video.
    • l10n – An array of button text and accessibility strings.

Theme support arguments

When calling add_theme_support( 'custom-header' ), two new arguments are available:

  • video – Registers support for video headers.
  • video-active-callback – Defines a callback used to determine whether a header video should be shown for the current request. Defaults to is_front_page.