WordPress Version: 6.3
/**
* Gets the default value to use for a `loading` attribute on an element.
*
* This function should only be called for a tag and context if lazy-loading is generally enabled.
*
* The function usually returns 'lazy', but uses certain heuristics to guess whether the current element is likely to
* appear above the fold, in which case it returns a boolean `false`, which will lead to the `loading` attribute being
* omitted on the element. The purpose of this refinement is to avoid lazy-loading elements that are within the initial
* viewport, which can have a negative performance impact.
*
* Under the hood, the function uses {@see wp_increase_content_media_count()} every time it is called for an element
* within the main content. If the element is the very first content element, the `loading` attribute will be omitted.
* This default threshold of 3 content elements to omit the `loading` attribute for can be customized using the
* {@see 'wp_omit_loading_attr_threshold'} filter.
*
* @since 5.9.0
* @deprecated 6.3.0 Use wp_get_loading_optimization_attributes() instead.
* @see wp_get_loading_optimization_attributes()
*
* @global WP_Query $wp_query WordPress Query object.
*
* @param string $context Context for the element for which the `loading` attribute value is requested.
* @return string|bool The default `loading` attribute value. Either 'lazy', 'eager', or a boolean `false`, to indicate
* that the `loading` attribute should be skipped.
*/
function wp_get_loading_attr_default($context)
{
_deprecated_function(__FUNCTION__, '6.3.0', 'wp_get_loading_optimization_attributes()');
global $wp_query;
// Skip lazy-loading for the overall block template, as it is handled more granularly.
if ('template' === $context) {
return false;
}
/*
* Do not lazy-load images in the header block template part, as they are likely above the fold.
* For classic themes, this is handled in the condition below using the 'get_header' action.
*/
$header_area = WP_TEMPLATE_PART_AREA_HEADER;
if ("template_part_{$header_area}" === $context) {
return false;
}
// Special handling for programmatically created image tags.
if ('the_post_thumbnail' === $context || 'wp_get_attachment_image' === $context) {
/*
* Skip programmatically created images within post content as they need to be handled together with the other
* images within the post content.
* Without this clause, they would already be counted below which skews the number and can result in the first
* post content image being lazy-loaded only because there are images elsewhere in the post content.
*/
if (doing_filter('the_content')) {
return false;
}
// Conditionally skip lazy-loading on images before the loop.
if ($wp_query->before_loop && $wp_query->is_main_query() && did_action('get_header') && !did_action('get_footer')) {
return false;
}
}
/*
* The first elements in 'the_content' or 'the_post_thumbnail' should not be lazy-loaded,
* as they are likely above the fold.
*/
if ('the_content' === $context || 'the_post_thumbnail' === $context) {
// Only elements within the main query loop have special handling.
if (is_admin() || !in_the_loop() || !is_main_query()) {
return 'lazy';
}
// Increase the counter since this is a main query content element.
$content_media_count = wp_increase_content_media_count();
// If the count so far is below the threshold, return `false` so that the `loading` attribute is omitted.
if ($content_media_count <= wp_omit_loading_attr_threshold()) {
return false;
}
// For elements after the threshold, lazy-load them as usual.
return 'lazy';
}
// Lazy-load by default for any unknown context.
return 'lazy';
}