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 8 commits into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
8 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
c495816
Fix mistaken attribute addition for audio interface
scottjehl Dec 12, 2025
f149247
apply suggested edits from @zcorpan
scottjehl Jan 14, 2026
e6c8d0d
Nits
zcorpan Jan 15, 2026
65e2159
Run specfmt
zcorpan Jan 15, 2026
bdb0fa6
add data-x=concept-n-noscript to span
scottjehl Jan 16, 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
168 changes: 155 additions & 13 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,14 +8053,14 @@ 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
steps</dfn>, initially null.</p>
<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
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
continue loading.</p>
<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 continue loading.</p>

<p>Each <code>Document</code> has a <dfn>lazy load intersection observer</dfn>, initially set to
null but can be set to an <code>IntersectionObserver</code> instance.</p>
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 can 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 @@ -37826,8 +37928,12 @@ 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
(this <span data-x="delay the load event">delays the load event</span>).</p></li>
<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 true (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
data-x="concept-task">task</span> that invoked this algorithm to continue. The <span>synchronous
Expand Down Expand Up @@ -38195,6 +38301,30 @@ 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 +39038,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 load resumption steps</span> are run.</p>

<hr>

<!--v3BUF (when readding this, also add a domintro block)
Expand Down Expand Up @@ -39600,6 +39735,10 @@ 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, or <span data-x="concept-n-noscript">scripting is
disabled</span> for the element;</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 +152290,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 +153328,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 +157022,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