Lazy-loading iframes in 5.7

In WordPress 5.7, iframes will be lazy-loaded by default, using the browser-level loading attribute. This will bring to iframes the same performance benefits which WordPress 5.5 introduced by lazy-loading images.

Similar to how it affects images, WordPress will add loading="lazy" to only those iframe tags that have both width and height attributes present, to avoid any perceived negative impact on layout shifting. The attribute is added on page output using the wp_filter_content_tags() function which was introduced in WordPress 5.5 with specifically that extensibility in mind which now allows reusing it for this new performance feature. Since the considerations of lazy-loading iframes are similar to those of lazy-loading images, please refer to the original image lazy-loading announcement post as well as this article on browser-level lazy-loading for background information on the topic.

See also #50756 for the ticketticket Created for both bug reports and feature development on the bug tracker. where this feature was worked on.

Impact on oEmbed content

By default, WordPress will add a loading="lazy" attribute to the following iframes:

  • iframes within post content (the_content)
  • iframes within post excerpts (the_excerpt)
  • iframes within text widgets (widget_text_content)

The majority of iframes used on WordPress sites typically come from its oEmbed integration, which will automatically transform a URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org to certain web platform resources (such as tweets or YouTube videos) into the referenced embedded media when pasted into the editor.

The markup of those iframe tags is controlled by the respective web service, and only some of those web services follow the best practice of providing width and height attribute. Since WordPress cannot guess the dimensions of the embedded resource, the loading="lazy" attribute will only be added if the oEmbed iframe tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.) comes with both dimension attributes present.

Customizing lazy-loading iframes

Developers can customize whether and how iframes are lazy-loaded in a similar way to how they can for images, with the primary filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. being the existing wp_lazy_loading_enabled, which going forward will return true for iframe tags by default.

For example, if you would like to turn off lazy-loading by default for iframes within post content, you could use the following code snippet:

function disable_post_content_iframe_lazy_loading( $default, $tag_name, $context ) {
	if ( 'iframe' === $tag_name && 'the_content' === $context ) {
		return false;
	}
	return $default;
}
add_filter(
	'wp_lazy_loading_enabled',
	'disable_post_content_iframe_lazy_loading',
	10,
	3
);

In addition, there is a new wp_iframe_tag_add_loading_attr filter which allows customization of a specific iframe tag. For example, you could use this filter to skip addition of the loading attribute on an iframeiframe iFrame is an acronym for an inline frame. An iFrame is used inside a webpage to load another HTML document and render it. This HTML document may also contain JavaScript and/or CSS which is loaded at the time when iframe tag is parsed by the user’s browser. that will likely appear within the initially visible viewport, to avoid impacting the Largest Contentful Paint metric. The filter has the same signature as the related wp_img_tag_add_loading_attr filter for images.

Here is an example code snippet which would disable lazy-loading iframes that embed YouTube videos within post content:

function skip_loading_lazy_youtube_iframes( $value, $iframe, $context ) {
	if ( 'the_content' === $context && false !== strpos( $iframe, 'youtube.com' ) ) {
		return false;
	}
	return $value;
}
add_filter(
	'wp_iframe_tag_add_loading_attr',
	'skip_loading_lazy_youtube_iframes',
	10,
	3
);

Please refer to the “Customizing lazy-loading” section of the image lazy-loading announcement post for additional guidance.

Props @audrasjb for proofreading.

#5-7, #dev-notes, #feature-lazyloading