Add support for video and audio element lazy-loading via the loading attribute by scottjehl · Pull Request #11980 · whatwg/html

scottjehl · 2025-12-02T18:27:08Z

Specify support for the loading attribute for the video element and audio element using similar conventions to img and iframe, where the attribute already has precedent. Loading has possible values of eager and lazy. When a media element's loading attribute value is lazy, loading of any video or poster image data, as well as autoplay playback, will defer until layout is known and the video is in the viewport.

Note Jan 22, 2026: Broadening PR to include Audio Element support.

Resolves #10376

At least two implementers are interested (and none opposed):
- Mozilla/Gecko Postion: Positive Add support for video element lazy-loading via the loading attribute mozilla/standards-positions#1325
- WebKit Position: Pending Add support for video and audio element lazy-loading via the loading attribute WebKit/standards-positions#586
- Chromium: Add support for video and audio element lazy-loading via the loading attribute #11980 (comment)
Tests are MERGED with tentative status:
- Web Platform Tests for HTML video and audio element lazy loading via the loading attribute web-platform-tests/wpt#57051
- PR to remove tentative when this lands Change HTML Video and Audio Lazy Loading Tests from Tentative to Non-Tentative web-platform-tests/wpt#57754
Implementation bugs are filed:
- Gecko: https://bugzilla.mozilla.org/show_bug.cgi?id=2005072
  - Firefox patch in Review https://phabricator.services.mozilla.com/D278547
- WebKit: https://bugs.webkit.org/show_bug.cgi?id=303995
  - WebKit Patch in Review: Implement HTML video and audio element lazy-loading via the loading attribute WebKit/WebKit#58220
- Chromium: https://issues.chromium.org/issues/469111735 https://chromestatus.com/feature/5200068565139456
  - Chromium patch MERGED behind a flag: https://chromium-review.googlesource.com/c/chromium/src/+/7511253
MDN issue is filed: Document HTMLMediaElement (Video & Audio) Lazy Loading (Experimental) mdn/mdn#809
The top of this comment includes a clear commit message to use.

(See WHATWG Working Mode: Changes for more details.)

/acknowledgements.html ( diff )
/indices.html ( diff )
/media.html ( diff )
/urls-and-fetching.html ( diff )

Specify support for the loading attribute for video using similar conventions to img and iframe, where the attribute has precedent. It has possible values of eager and lazy. When the loading attribute value is lazy, loading of any video or poster image data, as well as autoplay playback, must defer until layout is known and the video is in the viewport. This commit contains examples for how the loading attribute should take precedence over the preload, poster, and autoplay attributes. These were informed by experiments with local patch implementations to several user agents.

annevk · 2025-12-04T07:46:43Z

cc @whatwg/media

source

foolip · 2025-12-09T10:17:28Z

This direction makes sense to me, but I'm not personally able to make a commitment to implement in Chromium.

@zcorpan I think you've mentioned this feature, perhaps you have feedback?

Add detail for video element lazy loading behavior when loading state is lazy. This involves returning early to prevent poster and video data loading and defining resumption steps to resume when loading state changes to eager. Also includes notes about autoplay eligibility and precedence over the preload attribute.

source

Adjust language of this statement about precedence of the loading attribute over the preload attribute so that it reiterates a fact.

Remove mention as audio is not mentioned in this proposed attribute addition

…g attribute These tests support the proposal for the addition of a loading attribute on the video element, designed to enable lazy-loading for video and poster data. HTML Standard PR here whatwg/html#11980 Co-authored-by: Zach Lysobey <zlysobey@squarespace.com> Co-authored-by: Brad Frost <bfrost@squarespace.com> Co-authored-by: Credo Duarte <cduarte@squarespace.com>

scottjehl · 2026-01-07T22:24:02Z

Added and linked up a PR with web platform tests web-platform-tests/wpt#57051

small note: it says my entity is unverified above, but I think it's registered correctly now and needs a check

source

zcorpan · 2026-01-15T15:57:26Z

@scottjehl I tried to push changes to this branch but was denied. Can you enable "Allow edits from maintainers"?

scottjehl · 2026-01-15T16:07:02Z

@zcorpan I looked into how to do that and it sounds like the option may not be available for forks made by an organization, such as this one. Any other way we can help? Perhaps if the changes are in a public fork of yours I could pull them from there?

zcorpan · 2026-01-16T10:55:58Z

@scottjehl OK, pushed to https://github.com/zcorpan/html/tree/video-loading-attribute

scottjehl · 2026-01-16T12:40:00Z

@zcorpan looked great, thanks. Merged here!

source

…ttribute https://bugs.webkit.org/show_bug.cgi?id=303995 Reviewed by NOBODY (OOPS!). Implement proposed loading attribute for video and audio elements. This patch implements a proposed loading attribute for video and audio elements, enabling lazy loading of media sources and video poster images, and deferring autoplay. This change is proposed to be added to the HTML spec in the following PR: whatwg/html#11980 This patch is passing video and audio WPT tests from the following PR: web-platform-tests/wpt#57051 * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/Sources.txt: * Source/WebCore/WebCore.xcodeproj/project.pbxproj: * Source/WebCore/dom/Document.cpp: (WebCore::Document::lazyLoadMediaObserver): * Source/WebCore/dom/Document.h: * Source/WebCore/html/HTMLMediaElement.cpp: (WebCore::HTMLMediaElement::didMoveToNewDocument): (WebCore::HTMLMediaElement::attributeChanged): (WebCore::HTMLMediaElement::didFinishInsertingNode): (WebCore::HTMLMediaElement::removedFromAncestor): (WebCore::HTMLMediaElement::hasLazyLoadableAttributeValue): (WebCore::HTMLMediaElement::isLazyLoadable const): (WebCore::HTMLMediaElement::loadDeferredMedia): (WebCore::HTMLMediaElement::resumeLazyLoadingIfNeeded): (WebCore::HTMLMediaElement::loading const): (WebCore::HTMLMediaElement::setLoading): (WebCore::HTMLMediaElement::play): (WebCore::HTMLMediaElement::sourceWasAdded): (WebCore::HTMLMediaElement::setShouldDelayLoadEvent): * Source/WebCore/html/HTMLMediaElement.h: * Source/WebCore/html/HTMLMediaElement.idl: * Source/WebCore/html/HTMLVideoElement.cpp: (WebCore::HTMLVideoElement::rendererIsNeeded): (WebCore::HTMLVideoElement::supportsFullscreen const): (WebCore::HTMLVideoElement::hasAvailableVideoFrame const): (WebCore::HTMLVideoElement::webkitEnterFullscreen): (WebCore::HTMLVideoElement::loadDeferredMedia): * Source/WebCore/html/HTMLVideoElement.h: * Source/WebCore/html/LazyLoadMediaObserver.cpp: Added. (WebCore::LazyLoadMediaObserver::observe): (WebCore::LazyLoadMediaObserver::unobserve): (WebCore::LazyLoadMediaObserver::intersectionObserver): (WebCore::LazyLoadMediaObserver::isObserved const): * Source/WebCore/html/LazyLoadMediaObserver.h: Added. * Source/WebCore/html/parser/HTMLParserOptions.cpp: * Source/WebCore/html/parser/HTMLPreloadScanner.cpp: (WebCore::TokenPreloadScanner::StartTagScanner::processAttribute): * Source/WebCore/html/shadow/DataListButtonElement.cpp: * Source/WebCore/html/shadow/SpinButtonElement.cpp: * Source/WebCore/loader/ImageLoader.cpp: (WebCore::ImageLoader::updateFromElement): (WebCore::ImageLoader::didUpdateCachedImage): (WebCore::ImageLoader::notifyFinished): (WebCore::ImageLoader::updatedHasPendingEvent): (WebCore::ImageLoader::decode):

bkimmelSQSP · 2026-02-17T15:52:59Z

Are there any known outstanding issues preventing this from advancing to Stage 2?

…ttribute https://bugs.webkit.org/show_bug.cgi?id=303995 Reviewed by NOBODY (OOPS!). Implement proposed loading attribute for video and audio elements. This patch implements a proposed loading attribute for video and audio elements, enabling lazy loading of media sources and video poster images, and deferring autoplay. This change is proposed to be added to the HTML spec in the following PR: whatwg/html#11980 This patch is passing video and audio WPT tests from the following PR: web-platform-tests/wpt#57051 * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/Sources.txt: * Source/WebCore/WebCore.xcodeproj/project.pbxproj: * Source/WebCore/dom/Document.cpp: (WebCore::Document::lazyLoadMediaObserver): * Source/WebCore/dom/Document.h: * Source/WebCore/html/HTMLMediaElement.cpp: (WebCore::HTMLMediaElement::didMoveToNewDocument): (WebCore::HTMLMediaElement::attributeChanged): (WebCore::HTMLMediaElement::didFinishInsertingNode): (WebCore::HTMLMediaElement::removedFromAncestor): (WebCore::HTMLMediaElement::hasLazyLoadableAttributeValue): (WebCore::HTMLMediaElement::isLazyLoadable const): (WebCore::HTMLMediaElement::loadDeferredMedia): (WebCore::HTMLMediaElement::resumeLazyLoadingIfNeeded): (WebCore::HTMLMediaElement::loading const): (WebCore::HTMLMediaElement::setLoading): (WebCore::HTMLMediaElement::play): (WebCore::HTMLMediaElement::sourceWasAdded): (WebCore::HTMLMediaElement::setShouldDelayLoadEvent): * Source/WebCore/html/HTMLMediaElement.h: * Source/WebCore/html/HTMLMediaElement.idl: * Source/WebCore/html/HTMLVideoElement.cpp: (WebCore::HTMLVideoElement::rendererIsNeeded): (WebCore::HTMLVideoElement::supportsFullscreen const): (WebCore::HTMLVideoElement::hasAvailableVideoFrame const): (WebCore::HTMLVideoElement::webkitEnterFullscreen): (WebCore::HTMLVideoElement::loadDeferredMedia): * Source/WebCore/html/HTMLVideoElement.h: * Source/WebCore/html/LazyLoadMediaObserver.cpp: Added. (WebCore::LazyLoadMediaObserver::observe): (WebCore::LazyLoadMediaObserver::unobserve): (WebCore::LazyLoadMediaObserver::intersectionObserver): (WebCore::LazyLoadMediaObserver::isObserved const): * Source/WebCore/html/LazyLoadMediaObserver.h: Added. * Source/WebCore/html/parser/HTMLParserOptions.cpp: * Source/WebCore/html/parser/HTMLPreloadScanner.cpp: (WebCore::TokenPreloadScanner::StartTagScanner::processAttribute): * Source/WebCore/html/shadow/DataListButtonElement.cpp: * Source/WebCore/html/shadow/SpinButtonElement.cpp: * Source/WebCore/loader/ImageLoader.cpp: (WebCore::ImageLoader::updateFromElement): (WebCore::ImageLoader::didUpdateCachedImage): (WebCore::ImageLoader::notifyFinished): (WebCore::ImageLoader::updatedHasPendingEvent): (WebCore::ImageLoader::decode):

scottjehl · 2026-02-20T14:37:01Z

Updated the issue to note

the feature just merged in Chromium behind a feature flag.
Added an MDN issue and checked the box as done

scottjehl · 2026-02-23T20:23:52Z

Added a bulletpoint for our WebKit Patch, currently in Review: WebKit/WebKit#58220

…ttribute https://bugs.webkit.org/show_bug.cgi?id=303995 Reviewed by NOBODY (OOPS!). Implement proposed loading attribute for video and audio elements. This patch implements a proposed loading attribute for video and audio elements, enabling lazy loading of media sources and video poster images, and deferring autoplay. This change is proposed to be added to the HTML spec in the following PR: whatwg/html#11980 This patch is passing video and audio WPT tests from the following PR: web-platform-tests/wpt#57051 * Source/WTF/Scripts/Preferences/UnifiedWebPreferences.yaml: * Source/WebCore/Sources.txt: * Source/WebCore/WebCore.xcodeproj/project.pbxproj: * Source/WebCore/dom/Document.cpp: (WebCore::Document::lazyLoadMediaObserver): * Source/WebCore/dom/Document.h: * Source/WebCore/html/HTMLMediaElement.cpp: (WebCore::HTMLMediaElement::didMoveToNewDocument): (WebCore::HTMLMediaElement::attributeChanged): (WebCore::HTMLMediaElement::didFinishInsertingNode): (WebCore::HTMLMediaElement::removedFromAncestor): (WebCore::HTMLMediaElement::hasLazyLoadableAttributeValue): (WebCore::HTMLMediaElement::isLazyLoadable const): (WebCore::HTMLMediaElement::loadDeferredMedia): (WebCore::HTMLMediaElement::resumeLazyLoadingIfNeeded): (WebCore::HTMLMediaElement::loading const): (WebCore::HTMLMediaElement::setLoading): (WebCore::HTMLMediaElement::play): (WebCore::HTMLMediaElement::sourceWasAdded): (WebCore::HTMLMediaElement::setShouldDelayLoadEvent): * Source/WebCore/html/HTMLMediaElement.h: * Source/WebCore/html/HTMLMediaElement.idl: * Source/WebCore/html/HTMLVideoElement.cpp: (WebCore::HTMLVideoElement::rendererIsNeeded): (WebCore::HTMLVideoElement::supportsFullscreen const): (WebCore::HTMLVideoElement::hasAvailableVideoFrame const): (WebCore::HTMLVideoElement::webkitEnterFullscreen): (WebCore::HTMLVideoElement::loadDeferredMedia): * Source/WebCore/html/HTMLVideoElement.h: * Source/WebCore/html/LazyLoadMediaObserver.cpp: Added. (WebCore::LazyLoadMediaObserver::observe): (WebCore::LazyLoadMediaObserver::unobserve): (WebCore::LazyLoadMediaObserver::intersectionObserver): (WebCore::LazyLoadMediaObserver::isObserved const): * Source/WebCore/html/LazyLoadMediaObserver.h: Added. * Source/WebCore/html/parser/HTMLParserOptions.cpp: * Source/WebCore/html/parser/HTMLPreloadScanner.cpp: (WebCore::TokenPreloadScanner::StartTagScanner::processAttribute): * Source/WebCore/html/shadow/DataListButtonElement.cpp: * Source/WebCore/html/shadow/SpinButtonElement.cpp: * Source/WebCore/loader/ImageLoader.cpp: (WebCore::ImageLoader::updateFromElement): (WebCore::ImageLoader::didUpdateCachedImage): (WebCore::ImageLoader::notifyFinished): (WebCore::ImageLoader::updatedHasPendingEvent): (WebCore::ImageLoader::decode):

scottjehl · 2026-02-26T17:08:40Z

@zcorpan While refining our Firefox patch, we noticed that this spec may need to describe what happens when video methods such as play() and load() are called explicitly when loading is in the lazy state. We think such methods should take precedence over the loading attribute. Should this be in the spec?

…ttribute in media elements

scottjehl · 2026-02-27T20:14:13Z

A couple revisions today:

Made some updates to decouple poster and source resumption steps.
specified that load() and play() methods should override loading attr.

Curious to hear if these resolve the issues we'd discussed.
Thanks all.

zcorpan · 2026-03-04T14:55:53Z

source

+  data-x="dom-media-play">play()</code> methods take precedence over the <code
+  data-x="attr-media-loading">loading</code> attribute. When these methods are invoked, the user agent
+  must allow associated data loading and playback to proceed, regardless of the <code
+  data-x="attr-media-loading">loading</code> attribute's state.</p>


This is a bit action at a distance, and should be formalized in the relevant algorithms what exactly is expected.

Agreed. I gave it a shot. Over on the load() and play() methods.

Thanks. This paragraph should be removed.

Great. Done.

source

… invoke lazy load resumption steps before proceeding

zcorpan · 2026-03-05T13:20:51Z

source

+   <li><p>Let <var>resumptionSteps</var> be the <span>media element</span>'s <span>lazy load
+   resumption steps</span>.</p></li>
+
+   <li><p>If <var>resumptionSteps</var> is not null, then:</p>
+
+    <ol>
+     <li><p>Set the <span>media element</span>'s <span>lazy load resumption steps</span> to null.</p></li>
+
+     <li><p>Invoke <var>resumptionSteps</var>.</p></li>
+    </ol>
+   </li>
+


I think this should be moved down after the error-checking steps, so it's right before the step creating promise.

Thanks that makes sense. I moved it down.

…ng=lazy now that it's specified in their formal algorithms

This was referenced Dec 3, 2025

Add support for video and audio element lazy-loading via the loading attribute WebKit/standards-positions#586

Open

Add support for video element lazy-loading via the loading attribute mozilla/standards-positions#1325

Closed

annevk added addition/proposal New features or enhancements needs implementer interest Moving the issue forward requires implementers to express interest topic: media needs tests Moving the issue forward requires someone to write tests labels Dec 4, 2025

foolip reviewed Dec 9, 2025

View reviewed changes

source Outdated Show resolved Hide resolved

zcorpan reviewed Dec 11, 2025

View reviewed changes

source Outdated Show resolved Hide resolved

scottjehl added 2 commits December 11, 2025 11:34

Fix video element loading attribute precedence wording

33a79cf

Adjust language of this statement about precedence of the loading attribute over the preload attribute so that it reiterates a fact.

Fix mistaken attribute addition for audio interface

c495816

Remove mention as audio is not mentioned in this proposed attribute addition

scottjehl mentioned this pull request Jan 7, 2026

Web Platform Tests for HTML video and audio element lazy loading via the loading attribute web-platform-tests/wpt#57051

Merged

ryantownsend mentioned this pull request Jan 10, 2026

prefers-reduced-data media query web-platform-dx/developer-signals#314

Open

zcorpan requested changes Jan 14, 2026

View reviewed changes

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

source Outdated Show resolved Hide resolved

zcorpan removed needs implementer interest Moving the issue forward requires implementers to express interest needs tests Moving the issue forward requires someone to write tests labels Jan 14, 2026

apply suggested edits from @zcorpan

f149247

scottjehl requested a review from zcorpan January 14, 2026 17:41

zcorpan added 2 commits January 15, 2026 16:51

Nits

e6c8d0d

Run specfmt

65e2159

zcorpan reviewed Jan 16, 2026

View reviewed changes

source Outdated Show resolved Hide resolved

credod mentioned this pull request Feb 9, 2026

Implement HTML video and audio element lazy-loading via the loading attribute WebKit/WebKit#58220

Open

smaug---- reviewed Feb 10, 2026

View reviewed changes

source Show resolved Hide resolved

smaug---- reviewed Feb 10, 2026

View reviewed changes

source Show resolved Hide resolved

scottjehl mentioned this pull request Feb 12, 2026

Change HTML Video and Audio Lazy Loading Tests from Tentative to Non-Tentative web-platform-tests/wpt#57754

Open

scottjehl mentioned this pull request Feb 20, 2026

Document HTMLMediaElement (Video & Audio) Lazy Loading (Experimental) mdn/mdn#809

Open

scottjehl mentioned this pull request Feb 26, 2026

Upcoming WHATNOT meeting on 2026-02-26 #12202

Closed

cwilso added stage: 2 Iteration and removed stage: 1 Incubation labels Feb 26, 2026

scottjehl added 2 commits February 27, 2026 08:47

decouple poster and source resumption steps

3d28d69

specify that load and play methods take precedence over the loading a…

5136995

…ttribute in media elements

This was referenced Mar 3, 2026

Add lazy-loading for <video> and <audio> feature web-platform-dx/web-features#3837

Merged

Add loading-lazy-media: lazy loading for <video> and <audio> elements Fyrd/caniuse#7488

Merged

zcorpan requested changes Mar 4, 2026

View reviewed changes

scottjehl added 2 commits March 4, 2026 15:40

add qualifier for isIntersecting to posterResumptionSteps line

f0b03d7

for the media element load and play methods, add steps to nullify and…

e8a35c5

… invoke lazy load resumption steps before proceeding

scottjehl requested a review from zcorpan March 5, 2026 01:02

zcorpan reviewed Mar 5, 2026

View reviewed changes

scottjehl added 2 commits March 5, 2026 12:12

remove guidance on the precedence of load and play methods over loadi…

8dae529

…ng=lazy now that it's specified in their formal algorithms

move the lazy load resumption steps to later in the play method algo

4d9d54a

scottjehl requested a review from zcorpan March 5, 2026 18:58

Conversation

scottjehl commented Dec 2, 2025 • edited by pr-preview bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

annevk commented Dec 4, 2025

Uh oh!

Uh oh!

foolip commented Dec 9, 2025

Uh oh!

Uh oh!

scottjehl commented Jan 7, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zcorpan commented Jan 15, 2026

Uh oh!

scottjehl commented Jan 15, 2026

Uh oh!

zcorpan commented Jan 16, 2026

Uh oh!

scottjehl commented Jan 16, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bkimmelSQSP commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

scottjehl commented Feb 20, 2026

Uh oh!

scottjehl commented Feb 23, 2026

Uh oh!

scottjehl commented Feb 26, 2026

Uh oh!

scottjehl commented Feb 27, 2026

Uh oh!

zcorpan Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

scottjehl Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

zcorpan Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

scottjehl Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

zcorpan Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

scottjehl Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

10 participants

scottjehl commented Dec 2, 2025 •

edited by pr-preview bot

Loading

bkimmelSQSP commented Feb 17, 2026 •

edited

Loading