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 3 commits into
base: main
Choose a base branch
from
+141 −7
Open

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
58be9fd
Add support for video element lazy-loading via the loading attribute
scottjehl Dec 2, 2025
84d22f5
Add video element lazy-loading resumption steps
scottjehl Dec 10, 2025
33a79cf
Fix video element loading attribute precedence wording
scottjehl Dec 11, 2025
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
148 changes: 141 additions & 7 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 @@ -36436,7 +36439,11 @@ interface <dfn interface>HTMLVideoElement</dfn> : <span>HTMLMediaElement</span>
data-x="concept-request-destination">destination</span> is "<code data-x="">image</code>", <span
data-x="concept-request-initiator-type">initiator type</span> is "<code data-x="">video</code>",
<span data-x="concept-request-credentials-mode">credentials mode</span> is "<code
data-x="">include</code>", and whose <span>use-URL-credentials flag</span> is set.
data-x="">include</code>", and whose <span>use-URL-credentials flag</span> is set.</p></li>

<li><p>If the <span>will lazy load element steps</span> given the <code>video</code> return true,
then return.</p></li>


<li><p><!--FETCH--><span data-x="concept-fetch">Fetch</span> <var>request</var>. This must
<span>delay the load event</span> of the element's <span>node document</span>.</p></li>
Expand Down Expand Up @@ -36467,6 +36474,101 @@ 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>

<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>When the <code data-x="attr-video-loading">loading</code> attribute is in the
<span data-x="attr-loading-lazy-state">Lazy</span> state, it takes precedence over the
<code data-x="attr-media-preload">preload</code> attribute by deferring data fetching.</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 +36851,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 @@ -37826,7 +37929,9 @@ interface <dfn interface>MediaError</dfn> {

<li><p>Set the element's <span>show poster flag</span> to true.</p></li>

<li><p>Set the <span>media element</span>'s <span>delaying-the-load-event flag</span> to true
<li><p>If the <span>media element</span> is an <code>audio</code> element, or if the <span>media element</span> is a <code>video</code> element and its <span>lazy loading
attribute</span> is in the <span data-x="attr-loading-eager-state">Eager</span> state or
<span data-x="concept-n-noscript">scripting is disabled</span>, set the <span>media element</span>'s <span>delaying-the-load-event flag</span> to <var>delay load event</var>
(this <span data-x="delay the load event">delays the load event</span>).</p></li>

<li><p><span>Await a stable state</span>, allowing the <span
Expand Down Expand Up @@ -38195,6 +38300,24 @@ interface <dfn interface>MediaError</dfn> {
object</span> is as follows:</p>

<ol>
<li>
<p>If the <span>media element</span> is a <code>video</code> element and the <span>will lazy load element steps</span> given the <code>video</code> return true,
then:</p>

<ol>
<li><p>Let <var>resumptionSteps</var> be the rest of this algorithm starting with the step labeled <i>Let mode be remote</i>.</p></li>

<li><p>If the <code>video</code> has a <code data-x="attr-video-poster">poster</code> attribute specified and its value is not the empty string, then set <var>resumptionSteps</var> to an algorithm that runs the algorithm <var>resumptionSteps</var>, then runs the algorithm to determine the element's <span>poster frame</span> (as defined in the <code data-x="attr-video-poster">poster</code> attribute processing).</p></li>

<li><p>Set the <code>video</code>'s <span>lazy load resumption steps</span> to <var>resumptionSteps</var>.</p></li>

<li><p><span>Start intersection-observing a lazy loading element</span> for the
<code>video</code> element.</p></li>

<li><p>Return.</p></li>
</ol>
</li>

<li><p>Let <var>mode</var> be <i>remote</i>.</p></li>

<li>
Expand Down Expand Up @@ -38908,6 +39031,11 @@ interface <dfn interface>MediaError</dfn> {
has to buffer first, regardless of the hint given by the <code
data-x="attr-media-preload">preload</code> attribute). Including both is not an error, however.</p>

<p class="note">In <code>video</code> elements, if
<span data-x="concept-n-script">scripting is enabled</span>, the <code data-x="attr-video-loading">loading</code> attribute can defer the
<code data-x="attr-media-preload">preload</code> attribute's hinted behavior until the element's <span>lazy loading
attribute</span> is in the <span data-x="attr-loading-lazy-state">Lazy</span> state.</p>

<hr>

<!--v3BUF (when readding this, also add a domintro block)
Expand Down Expand Up @@ -39600,6 +39728,9 @@ interface <dfn interface>MediaError</dfn> {
<li><p>it has an <code data-x="attr-media-autoplay">autoplay</code> attribute
specified;</p></li>

<li><p>if it is a <code>video</code> element and its <span>lazy loading attribute</span> is not in the
<span data-x="attr-loading-lazy-state">Lazy</span> state;</p></li>

<li><p>its <span>node document</span>'s <span>active sandboxing flag set</span> does not have
the <span>sandboxed automatic features browsing context flag</span> set; and</p></li>

Expand Down Expand Up @@ -152151,6 +152282,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 +153320,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 +157014,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