Skip to content

Add native loading=lazy support for video elements #2450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
adamsilverstein wants to merge 6 commits into
base: trunk
Choose a base branch
from
Open

Add native loading=lazy support for video elements #2450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
39f797e
Add native loading=lazy support for video elements
adamsilverstein Apr 9, 2026
668f515
Merge branch 'trunk' into add-native-video-support
adamsilverstein Apr 23, 2026
771be4f
Apply suggestions from code review
adamsilverstein May 11, 2026
e871d03
Short-circuit lazy video IntersectionObserver when native lazy-loadin…
adamsilverstein May 11, 2026
d8e6794
Update test snapshots to reflect renamed const in lazy-load-video.js
adamsilverstein May 11, 2026
167c0da
Merge branch 'trunk' into add-native-video-support
westonruter Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions plugins/image-prioritizer/class-image-prioritizer-video-tag-visitor.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -216,14 +216,19 @@ private function lazy_load_videos( ?string $poster, OD_Tag_Visitor_Context $cont
if ( 'auto' !== $initial_preload ) {
$processor->set_attribute( 'preload', 'auto' );
}
$processor->remove_attribute( 'loading' );
return;
}

// If the element is visible in any viewport, do not lazy-load it.
if ( $max_intersection_ratio > 0 ) {
$processor->remove_attribute( 'loading' );
return;
}

// Add native lazy loading for browsers that support it.
$processor->set_attribute( 'loading', 'lazy' );

if ( 'none' !== $initial_preload ) {
$processor->set_attribute( 'data-original-preload', null !== $initial_preload ? $initial_preload : 'default' );
$processor->set_attribute( 'preload', 'none' );
Expand Down
72 changes: 42 additions & 30 deletions plugins/image-prioritizer/lazy-load-video.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,50 @@
const lazyVideoObserver = new IntersectionObserver(
( entries ) => {
for ( const entry of entries ) {
if ( entry.isIntersecting ) {
const video = /** @type {HTMLVideoElement} */ entry.target;
const restoreVideo = ( /** @type {HTMLVideoElement} */ video ) => {
const poster = video.getAttribute( 'data-original-poster' );
if ( poster ) {
video.setAttribute( 'poster', poster );
}

const poster = video.getAttribute( 'data-original-poster' );
if ( poster ) {
video.setAttribute( 'poster', poster );
}
if ( video.hasAttribute( 'data-original-autoplay' ) ) {
video.setAttribute( 'autoplay', 'autoplay' );
}

if ( video.hasAttribute( 'data-original-autoplay' ) ) {
video.setAttribute( 'autoplay', 'autoplay' );
}
const preload = video.getAttribute( 'data-original-preload' );
if ( preload ) {
if ( 'default' === preload ) {
video.removeAttribute( 'preload' );
} else {
video.setAttribute( 'preload', preload );
}
}
};

const preload = video.getAttribute( 'data-original-preload' );
if ( preload ) {
if ( 'default' === preload ) {
video.removeAttribute( 'preload' );
} else {
video.setAttribute( 'preload', preload );
}
}
const videos = document.querySelectorAll( 'video.od-lazy-video' );

lazyVideoObserver.unobserve( video );
// When the browser natively supports lazy-loading on video, restore the original
// attributes immediately and rely on loading="lazy" to defer the video load.
if ( 'loading' in HTMLMediaElement.prototype ) {
for ( const video of videos ) {
restoreVideo( /** @type {HTMLVideoElement} */ ( video ) );
}
} else {
const lazyVideoObserver = new IntersectionObserver(
( entries ) => {
for ( const entry of entries ) {
if ( entry.isIntersecting ) {
restoreVideo(
/** @type {HTMLVideoElement} */ ( entry.target )
);
lazyVideoObserver.unobserve( entry.target );
}
}
},
{
rootMargin: '100% 0% 100% 0%',
threshold: 0,
Comment on lines +30 to +43
Copy link
Copy Markdown
Member

@westonruter westonruter May 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Something that just came to mind: What about sites that are configured with infinite scroll? The newly-inserted content could come in with the autoplay and preload attributes removed.

Perhaps this is unlikely because it would mean Image Prioritizer would have to be running on the Ajax response.

Also, worst case is it means the video wouldn't get preloaded, meaning the user would have to click it to play. Not the end of the world. Since it is implemented in Chrome now, appears to be implemented behind a flag in Firefox and the Safari implementation is also moving along, I expect we can soon eliminate the JS here entirely.

}
},
{
rootMargin: '100% 0% 100% 0%',
threshold: 0,
}
);
);

const videos = document.querySelectorAll( 'video.od-lazy-video' );
for ( const video of videos ) {
lazyVideoObserver.observe( video );
for ( const video of videos ) {
lazyVideoObserver.observe( video );
}
}
8 changes: 4 additions & 4 deletions plugins/image-prioritizer/tests/test-cases/multiple-videos-on-all-breakpoints/expected.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 13 additions & 0 deletions plugins/image-prioritizer/tests/test-cases/video-hidden-on-all-breakpoints/buffer.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<html lang="en">
<head>
<meta charset="utf-8">
<title>...</title>
<meta name="generator" content="optimization-detective 0.0.0">
<meta name="generator" content="image-prioritizer 0.0.0">
</head>
<body>
<div id="page">
<video class="desktop" width="1200" height="500" src="https://example.com/header.mp4" preload="auto" autoplay></video>
</div>
</body>
</html>
16 changes: 16 additions & 0 deletions plugins/image-prioritizer/tests/test-cases/video-hidden-on-all-breakpoints/expected.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions plugins/image-prioritizer/tests/test-cases/video-hidden-on-all-breakpoints/set-up.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php
return static function ( Test_Image_Prioritizer_Helper $test_case ): void {
$breakpoint_max_widths = array( 480, 600, 782 );

add_filter(
'od_breakpoint_max_widths',
static function () use ( $breakpoint_max_widths ) {
return $breakpoint_max_widths;
}
);

foreach ( array_merge( $breakpoint_max_widths, array( 1000 ) ) as $viewport_width ) {
$test_case->store_url_metric(
od_get_url_metrics_slug( od_get_normalized_query_vars() ),
$test_case->get_sample_url_metric(
array(
'viewport_width' => $viewport_width,
'elements' => array(
array(
'isLCP' => false,
'xpath' => '/HTML/BODY/DIV[@id=\'page\']/*[1][self::VIDEO]',
'boundingClientRect' => $test_case->get_sample_dom_rect(),
'intersectionRatio' => 0.0,
),
),
)
)
);
}
};
13 changes: 13 additions & 0 deletions ...ioritizer/tests/test-cases/video-with-loading-lazy-already-set-and-is-visible/buffer.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<html lang="en">
<head>
<meta charset="utf-8">
<title>...</title>
<meta name="generator" content="optimization-detective 0.0.0">
<meta name="generator" content="image-prioritizer 0.0.0">
</head>
<body>
<div id="page">
<video class="desktop" poster="https://example.com/poster.jpg" width="1200" height="500" src="https://example.com/header.mp4" loading="lazy"></video>
</div>
</body>
</html>
15 changes: 15 additions & 0 deletions ...ritizer/tests/test-cases/video-with-loading-lazy-already-set-and-is-visible/expected.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions ...rioritizer/tests/test-cases/video-with-loading-lazy-already-set-and-is-visible/set-up.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php
return static function ( Test_Image_Prioritizer_Helper $test_case ): void {
$breakpoint_max_widths = array( 480, 600, 782 );

add_filter(
'od_breakpoint_max_widths',
static function () use ( $breakpoint_max_widths ) {
return $breakpoint_max_widths;
}
);

foreach ( array_merge( $breakpoint_max_widths, array( 1000 ) ) as $viewport_width ) {
$test_case->store_url_metric(
od_get_url_metrics_slug( od_get_normalized_query_vars() ),
$test_case->get_sample_url_metric(
array(
'viewport_width' => $viewport_width,
'elements' => array(
array(
'isLCP' => false,
'xpath' => '/HTML/BODY/DIV[@id=\'page\']/*[1][self::VIDEO]',
'boundingClientRect' => $test_case->get_sample_dom_rect(),
'intersectionRatio' => 0.5,
),
),
)
)
);
}
};
13 changes: 13 additions & 0 deletions ...ins/image-prioritizer/tests/test-cases/video-with-loading-lazy-on-lcp-element/buffer.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<html lang="en">
<head>
<meta charset="utf-8">
<title>...</title>
<meta name="generator" content="optimization-detective 0.0.0">
<meta name="generator" content="image-prioritizer 0.0.0">
</head>
<body>
<div id="page">
<video class="desktop" poster="https://example.com/poster.jpg" width="1200" height="500" src="https://example.com/header.mp4" loading="lazy"></video>
</div>
</body>
</html>
16 changes: 16 additions & 0 deletions ...s/image-prioritizer/tests/test-cases/video-with-loading-lazy-on-lcp-element/expected.html
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

30 changes: 30 additions & 0 deletions plugins/image-prioritizer/tests/test-cases/video-with-loading-lazy-on-lcp-element/set-up.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
<?php
return static function ( Test_Image_Prioritizer_Helper $test_case ): void {
$breakpoint_max_widths = array( 480, 600, 782 );

add_filter(
'od_breakpoint_max_widths',
static function () use ( $breakpoint_max_widths ) {
return $breakpoint_max_widths;
}
);

foreach ( array_merge( $breakpoint_max_widths, array( 1000 ) ) as $viewport_width ) {
$test_case->store_url_metric(
od_get_url_metrics_slug( od_get_normalized_query_vars() ),
$test_case->get_sample_url_metric(
array(
'viewport_width' => $viewport_width,
'elements' => array(
array(
'isLCP' => true,
'xpath' => '/HTML/BODY/DIV[@id=\'page\']/*[1][self::VIDEO]',
'boundingClientRect' => $test_case->get_sample_dom_rect(),
'intersectionRatio' => 1.0,
),
),
)
)
);
}
};