Skip to content

Add support for video element lazy-loading via the loading attribute #11980

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
scottjehl wants to merge 1 commit into
base: main
Choose a base branch
from
+108 −5
Open

Add support for video element lazy-loading via the loading attribute #11980

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
113 changes: 108 additions & 5 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8010,11 +8010,11 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<th>Brief description
<tbody>
<tr>
<td><dfn attr-value for="img/loading,iframe/loading"><code data-x="attr-loading-lazy">lazy</code></dfn>
<td><dfn attr-value for="img/loading,video/loading,iframe/loading"><code data-x="attr-loading-lazy">lazy</code></dfn>
<td><dfn data-x="attr-loading-lazy-state">Lazy</dfn>
<td>Used to defer fetching a resource until some conditions are met.
<tr>
<td><dfn attr-value for="img/loading,iframe/loading"><code data-x="attr-loading-eager">eager</code></dfn>
<td><dfn attr-value for="img/loading,video/loading,iframe/loading"><code data-x="attr-loading-eager">eager</code></dfn>
<td><dfn data-x="attr-loading-eager-state">Eager</dfn>
<td>Used to fetch a resource immediately; the default state.
</table>
Expand Down Expand Up @@ -8053,10 +8053,10 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
</ol>
</div>

<p>Each <code>img</code> and <code>iframe</code> element has associated <dfn>lazy load resumption
<p>Each <code>img</code>, <code>video</code>, and <code>iframe</code> element has associated <dfn>lazy load resumption
steps</dfn>, initially null.</p>

<p class="note">For <code>img</code> and <code>iframe</code> elements that <span data-x="will lazy
<p class="note">For <code>img</code>, <code>video</code>, and <code>iframe</code> elements that <span data-x="will lazy
load element steps">will lazy load</span>, these steps are run from the <span>lazy load
intersection observer</span>'s callback or when their <span>lazy loading attribute</span> is set
to the <span data-x="attr-loading-eager-state">Eager</span> state. This causes the element to
Expand Down Expand Up @@ -36349,6 +36349,7 @@ interface <dfn interface>HTMLObjectElement</dfn> : <span>HTMLElement</span> {
<dd><code data-x="attr-media-loop">loop</code></dd>
<dd><code data-x="attr-media-muted">muted</code></dd>
<dd><code data-x="attr-media-controls">controls</code></dd>
<dd><code data-x="attr-video-loading">loading</code></dd>
<dd><code data-x="attr-dim-width">width</code></dd>
<dd><code data-x="attr-dim-height">height</code></dd>
<dt><span
Expand All @@ -36367,6 +36368,8 @@ interface <dfn interface>HTMLVideoElement</dfn> : <span>HTMLMediaElement</span>
readonly attribute unsigned long <span data-x="dom-video-videoHeight">videoHeight</span>;
[<span>CEReactions</span>, <span data-x="xattr-ReflectURL">ReflectURL</span>] attribute USVString <dfn attribute for="HTMLVideoElement" data-x="dom-video-poster">poster</dfn>;
[<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>] attribute boolean <dfn attribute for="HTMLVideoElement" data-x="dom-video-playsInline">playsInline</dfn>;
[<span>CEReactions</span>] attribute DOMString <span data-x="dom-video-loading">loading</span>;

};</code></pre>
</dd>
<dd w-dev>Uses <code>HTMLVideoElement</code>.</dd>
Expand Down Expand Up @@ -36467,6 +36470,102 @@ interface <dfn interface>HTMLVideoElement</dfn> : <span>HTMLMediaElement</span>
agents have chosen to play all videos inline by default, and in such user agents the <code
data-x="attr-video-playsinline">playsinline</code> attribute has no effect.</p>

<p>The <dfn element-attr for="video" data-x="attr-video-loading"><code>loading</code></dfn> attribute is a <span>lazy
loading attribute</span>. Its purpose is to indicate the policy for loading videos that are
outside the viewport.</p>

<div algorithm>
<p>When the <code data-x="attr-video-loading">loading</code> attribute's state is changed to the
<span data-x="attr-loading-eager-state">Eager</span> state, the user agent must run these
steps:</p>

<ol>
<li><p>Let <var>resumptionSteps</var> be the <code>video</code> element's <span>lazy load
resumption steps</span>.</p></li>

<li><p>If <var>resumptionSteps</var> is null, then return.</p></li>

<li><p>Set the <code>video</code>'s <span>lazy load resumption steps</span> to null.</p></li>
Copy link
Member

@foolip foolip Dec 9, 2025

Choose a reason for hiding this comment

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

Where is video's lazy load resumption steps set to a non-null value? Is a call to "start intersection-observing a lazy loading element" needed somewhere to make it all work?


<li><p>Invoke <var>resumptionSteps</var>.</p></li>
</ol>
</div>

<div algorithm>
<p>The <dfn attribute for="HTMLVideoElement"><code data-x="dom-video-loading">loading</code></dfn>
IDL attribute must <span>reflect</span> the <code data-x="attr-video-loading">loading</code> content
attribute, <span>limited to only known values</span>.</p>
</div>

<p>The <code data-x="attr-video-loading">loading</code> attribute takes precedence over the <code data-x="attr-media-preload">preload</code>
attribute: if the <code data-x="attr-video-loading">loading</code> attribute is in the <span
data-x="attr-loading-lazy-state">Lazy</span> state, data fetching <em>must</em> be deferred regardless
of the value or absence of <code>preload</code>.</p>

<p>If the <code data-x="attr-media-autoplay">autoplay</code> attribute is present and the <code data-x="attr-video-loading">loading</code>
attribute is in the <span data-x="attr-loading-lazy-state">Lazy</span> state, the user agent must
also defer starting playback (and any associated network requests autoplay may introduce) until the element's <span>lazy load
resumption steps</span> are invoked.</p>

<p>If the <code data-x="attr-video-poster">poster</code> attribute is present and the <code data-x="attr-video-loading">loading</code>
attribute is in the <span data-x="attr-loading-lazy-state">Lazy</span> state, the user agent must
defer loading the poster image source data until the element's <span>lazy load
resumption steps</span> are invoked.</p>

<div class="example">
<pre><code class="html">&lt;video src="1.mp4" poster="1.jpg" type="video/mp4">
&lt;video src="2.mp4" type="video/mp4" loading="eager">
&lt;video src="3.mp4" type="video/mp4" loading="lazy">
&lt;video src="4.mp4" type="video/mp4" loading="lazy" autoplay>
&lt;div id="very-large">&lt;/div> &lt;!-- Everything after this div is below the viewport -->
&lt;video src="5.mp4" type="video/mp4">
&lt;video src="6.mp4" type="video/mp4" loading="lazy">
&lt;video src="7.mp4" type="video/mp4" autoplay loading="lazy">
&lt;video src="8.mp4" type="video/mp4" poster="8.jpg" loading="lazy">
&lt;video src="9.mp4" type="video/mp4" preload="none" poster="9.jpg" loading="lazy">
&lt;video src="10.mp4" type="video/mp4" preload="metadata" loading="lazy"></code></pre>

<p>In the example above, the videos load as follows:</p>

<dl class="switch">
<dt><code data-x="">1.mp4</code></dt>
<dd><p>The video and poster image load eagerly and delay the window's load event.</p></dd>

<dt><code data-x="">2.mp4</code>,
<code data-x="">5.mp4</code></dt>
<dd><p>The videos load eagerly and delay the window's load event.</p></dd>

<dt><code data-x="">3.mp4</code></dt>
<dd><p>The video loads when layout is known, due to being in the viewport, however it does not
delay the window's load event.</p></dd>

<dt><code data-x="">4.mp4</code></dt>
<dd><p>The video loads and autoplay playback begins when layout is known, due to being in the viewport, however it does not
delay the window's load event.</p></dd>

<dt><code data-x="">6.mp4</code></dt>
<dd><p>The video loads only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>

<dt><code data-x="">7.mp4</code></dt>
<dd><p>The video loads and autoplay playback begins only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>

<dt><code data-x="">8.mp4</code></dt>
<dd><p>The video and poster image load only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>

<dt><code data-x="">9.mp4</code></dt>
<dd><p>The video does not load until played. The poster image loads only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>

<dt><code data-x="">10.mp4</code></dt>
<dd><p>The video's metadata loads only once scrolled into the viewport, and does not delay the window's
load event.</p></dd>
</dl>
</div>


<div w-nodev>

<hr>
Expand Down Expand Up @@ -36749,6 +36848,7 @@ zero or more <code>track</code> elements, then
<dd><code data-x="attr-media-loop">loop</code></dd>
<dd><code data-x="attr-media-muted">muted</code></dd>
<dd><code data-x="attr-media-controls">controls</code></dd>
<dd><code data-x="attr-video-loading">loading</code></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-audio">For authors</a>.</dd>
Expand Down Expand Up @@ -152151,6 +152251,7 @@ interface <dfn interface>External</dfn> {
<code data-x="attr-media-preload">preload</code>;
<code data-x="attr-media-autoplay">autoplay</code>;
<code data-x="attr-video-playsinline">playsinline</code>;
<code data-x="attr-video-loading">loading</code>;
<code data-x="attr-media-loop">loop</code>;
<code data-x="attr-media-muted">muted</code>;
<code data-x="attr-media-controls">controls</code>;
Expand Down Expand Up @@ -153188,7 +153289,8 @@ interface <dfn interface>External</dfn> {
<tr>
<th> <code data-x="">loading</code>
<td> <code data-x="attr-iframe-loading">iframe</code>;
<code data-x="attr-img-loading">img</code>
<code data-x="attr-img-loading">img</code>;
<code data-x="attr-video-loading">video</code>
<td> Used when determining loading deferral
<td> "<code data-x="attr-loading-lazy">lazy</code>";
"<code data-x="attr-loading-eager">eager</code>"
Expand Down Expand Up @@ -156881,6 +156983,7 @@ INSERT INTERFACES HERE
Scott Beardsley,
Scott Gonz&aacute;lez,
Scott Hess,
Scott Jehl,
Scott Miles,
Scott O'Hara,
Sean B. Palmer, <!-- sbp on GitHub -->
Expand Down