Add <template for> for declarative out-of-order streaming by foolip · Pull Request #11818 · whatwg/html

foolip · 2025-10-22T15:04:53Z

At least two implementers are interested (and none opposed):
- …
- …
Tests are written and can be reviewed and commented upon at:
- …
Implementation bugs are filed:
- Chromium: …
- Gecko: …
- WebKit: …
- Deno (only for timers, structured clone, base64 utils, channel messaging, module resolution, web workers, and web storage): …
- Node.js (only for timers, structured clone, base64 utils, channel messaging, and module resolution): …
Corresponding HTML AAM & ARIA in HTML issues & PRs:
MDN issue is filed: …
The top of this comment includes a clear commit message to use.

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

/indices.html ( diff )
/infrastructure.html ( diff )
/parsing.html ( diff )
/scripting.html ( diff )
/timers-and-user-prompts.html ( diff )

foolip · 2025-11-06T12:04:54Z

I've made some additional changes but things don't quite make sense yet. The direction I'm heading in is:

When the parser encounters an <template contentmethod> element, it doesn't insert it.
In insert an element at the adjusted insertion location, if we're about to insert an element with a contentname attribute into such a <template> element:
- Find the target element among the descendents of the element that the <template> element was in. That target is kept as a bookkeeping slot, the tree traversal only happens once.
- For contentmethod=replace, remove the target and actually insert. (For the following cases, the element isn't inserted.)
- For contentmethod=replace-children, remove the children.
- For contentmethod=prepend, save the current first element of the target.
- For contentmethod=append, there's nothing to do here.
In appropriate place for inserting a node further adjust the location based on contentmethod after the existing foster parenting adjustments. (This happens before the above step, but isn't relevant in that case.)
In insert an element at the adjusted insertion location, if we're about to insert into an element with a contentname attribute and the bookkeeping all checks out:
- For contentmethod=replace-children and contentmethod=append, just append.
- For contentmethod=prepend, use the saved first element of the target.

There are options for where to store the bookkeeping. I initially put it on the <template> element but now think it might be easier to follow if the bookkeeping goes on the element with the contentname attribute. An implementation might keep it as extra information in the stack of open elements.

noamr · 2025-11-06T12:08:12Z

I've made some additional changes but things don't quite make sense yet. The direction I'm heading in is:

When the parser encounters an <template contentmethod> element, it doesn't insert it.

contentmethod also needs to be valid

In insert an element at the adjusted insertion location, if we're about to insert an element with a contentname attribute into such a <template> element:

Find the target element among the descendents of the element that the <template> element was in. That target is kept as a bookkeeping slot, the tree traversal only happens once.

For contentmethod=replace, remove the target and actually insert. (For the following cases, the element isn't inserted.)

For contentmethod=replace-children, remove the children.

For contentmethod=prepend, save the current first element of the target.

For contentmethod=append, there's nothing to do here.

In appropriate place for inserting a node further adjust the location based on contentmethod after the existing foster parenting adjustments. (This happens before the above step, but isn't relevant in that case.)

In insert an element at the adjusted insertion location, if we're about to insert into an element with a contentname attribute and the bookkeeping all checks out:

For contentmethod=replace-children and contentmethod=append, just append.

For contentmethod=prepend, use the saved first element of the target.

It also needs to fail if that first element is no longer a child of the target.

There are options for where to store the bookkeeping. I initially put it on the <template> element but now think it might be easier to follow if the bookkeeping goes on the element with the contentname attribute. An implementation might keep it as extra information in the stack of open elements.

Yea makes sense, that way you don't have to deal with grandparents.

foolip · 2025-11-08T12:18:51Z

I've now rewritten a lot of this to make it match my previous comment, and I think it's in good enough shape for review now.

I left two inline issues:

If target's first child was moved or removed, the element will be appended to target below. Should the node be dropped instead, or should we update content target first child and keep inserting before it?

and

Patching head from within head is not possible but could easily be supported.

@noamr for the first one, you said we should fail, but what would that mean?

noamr · 2025-11-08T13:17:50Z

I've now rewritten a lot of this to make it match my previous comment, and I think it's in good enough shape for review now.

I left two inline issues:

If target's first child was moved or removed, the element will be appended to target below. Should the node be dropped instead, or should we update content target first child and keep inserting before it?

and

Patching head from within head is not possible but could easily be supported.

@noamr for the first one, you said we should fail, but what would that mean?

It means no further content is prepended.

foolip · 2025-11-09T21:59:40Z

Okay, should that state be sticky, or what happens if the nodes later realign so that the check passes?

noamr · 2025-11-10T06:47:30Z

Okay, should that state be sticky, or what happens if the nodes later realign so that the check passes?

Yea I think it errors the whole thing

noamr · 2025-11-11T21:04:06Z

Missing pieces following the TPAC session:

Applying patches inside the fragment parser (e.g. innerHTML) should be guarded in the same way as declarative shadow root, to avoid breaking assumptions made by userland sanitizers like DOMPurify.
Find a way to notify in case of an error instead of failing silently. e.g. dispatch some error event on the document with a reference to the detached template element.
Ensure that this works correctly when patching the child text nodes of scripts/styles, given that those elements have been "closed" before.

foolip · 2025-11-14T10:19:52Z

I've given some thoughts to error handling for contentmethod=prepend. Here's an example of the problem:

<!doctype html>
<body>
<div contentname=foo><span id=refnode>will be removed</span></div>

<template contentmethod=prepend>
  <div contentname=foo>
    <p>this element is inserted</p>
    <!-- the script removes the "content target first child" node -->
    <script>window.refnode = document.getElementById('refnode'); refnode.remove();</script>
    <p>reference node is gone, can this element be inserted?</p>
    <!-- put the reference node back -->
    <script>document.querySelector('[contentname=foo]').appendChild(refnode);</script>
    <p>is this OK because the reference node is back?</p>
  </div>
  <div contentname=foo>
    <p>is this fine because we saved a new reference node?</p>
  </div>
</template>

Options on what constitutes an error:

Reference node is not a child of target
Reference node has no parent (such that any parent would do)

Options on handling:

Error is transient and if the error condition goes away, we keep inserting
Error state is sticky to the <div contentname=foo>, skipping the rest of that patch
Error state is sticky to the <template contentmethod=prepend>, skipping the rest of the current patch and any others in the template
For sticky error states, it could be set either when the condition is broken (refnode.remove()) or when we discover that it is broken (when inserting the node after the script)

Options on reporting:

Nothing, nodes are silently dropped, at most with devtools warnings
Queue a task to fire a bubbling "contenterror" event at the template element's would-be parent. Could also be the would-be parent's root, more like the "unhandledrejection".
- Either one event for every failed insertion or
- one event for the first error or summarizing all errors.

It looks like the parser currently never fires events while it's still running, the only events are "DOMContentLoaded" and "load". Anything else that seems be fired by parsing is actually triggered by some other algorithm run as a side effect of what the parser does.

I don't think that parse errors are a good fit either, because the error can't easily be expressed in terms of the input, but the shape of the DOM tree.

My thinking now is that we should instead guarantee that the nodes are inserted, that we don't discard node midstream. For contentmethod=prepend the model I think could work is maintaining an insertion point within the target element that is updated if children are removed.

foolip · 2025-11-20T10:28:18Z

Applying patches inside the fragment parser (e.g. innerHTML) should be guarded in the same way as declarative shadow root, to avoid breaking assumptions made by userland sanitizers like DOMPurify.

This is controlled by https://dom.spec.whatwg.org/#concept-document-allow-declarative-shadow-roots. We should probably rename this to cover both of these behaviors.

foolip · 2026-03-09T10:58:02Z

I've pushed a change to rewrite this as <template for> using processing instructions <?marker>, <?start>, and <?end>.

This depends on three other PRs:

noamr · 2026-03-10T11:42:41Z

+        <p>If <var>scope</var> is a <code>template</code> element, then set <var>scope</var> to
+        <var>scope</var>'s <span>template contents</span>.</p>
+
+        <p class="note">This is to support patching inside <code>template</code> elements.</p>


Suggested change

<p class="note">This is to support patching inside <code>template</code> elements.</p>

<p class="note">This is to support patching inside <code>template</code> elements. It

would work for normal templates or declarative shadow roots, however it effectively disallows

nested patches, as the <span>template contents</span> is separate from the <span>insertion

target</span></p>

noamr · 2026-03-18T21:54:40Z

+     <li><p>Let <var>nextNode</var> be <var>currentNode</var>'s
+     <span>next sibling</span>.</p></li>
+
+     <li><p><span data-x="concept-node-remove">Remove</span> <var>currentNode</var>.</p></li>


This can have impllications if the node is an iframe with a pagehide, e.g. it can synchronously add more siblings or change things about the document. It's perhaps OK but an alternative would be to accumulate all the nodes before the <?end> and then remove them in one go.

How would you remove them all at once? That's not a primitive that we have. How do we account for changes here?

Changes in there won't have any effect. You'd have accumulated a list of nodes in this step, and then when we see <?end> we remove all of those one by one. If there is a pagehide or whatnot for one of them it wouldn't be able to change that list.

That is probably a good idea.

We probably still need to add guards though because concept-node-remove for instance asserts node's parent is non-null.

Right, those should generally behave like Node.prototype.remove()

annevk · 2026-05-08T12:52:25Z

  [<span>HTMLConstructor</span>] constructor();

  readonly attribute <span>DocumentFragment</span> <span data-x="dom-template-content">content</span>;
+  [<span>CEReactions</span>, <span data-x="xattr-Reflect">Reflect</span>="<span data-x="attr-template-for">for</span>"] attribute DOMString <dfn attribute for="HTMLTemplateElement" data-x="dom-template-htmlFor">htmlFor</dfn>;


Why do we use htmlFor here? I thought that was no longer needed given changes to ECMAScript? We should use for.

OTOH, do we really want the naming convention to be different for the same-named attribute on different HTML elements?

I guess it depends on if we try to proceed with #9379 for the other cases.

I think at this point it would be preferable to expose it as htmlFor and have aliases for all of them when we decide on #9379 rather than end up with a mix and match of for and htmlFor.

I guess I don't feel super strongly myself, but web developers really seem to dislike the prefix so I'm somewhat hesitant to spread it further.

I wonder if @jakearchibald or @tunetheweb have a strong opinion about this. My opinion right now is that we should fix all of these together but I could be convinced that drawing the line here makes more sense.

No strong opinion myself but do agree that it seems weird to fix this one (and not support htmlFor at all?) while htmlFor is still the "standard" way IIUC?

Suggesting to resolve this comment for now. We are likely to get mixed opinions from developers. Let's create aliases for this together with #9379.

Discussed this with @jakearchibald on #9379 as well. There is rough consensus on the plan of starting with htmlFor and aliasing all of those attributes to for (+ class) when we resolve on that.

annevk · 2026-05-08T12:55:05Z

+     <th> <code data-x="">for</code>
+     <td> <code data-x="attr-template-for">template</code>
+     <td> Updates existing content
+     <td> Text


It looks like we're missing an update to the template element index entry.

annevk · 2026-05-08T12:59:05Z

+     <li><p>Let <var>nextNode</var> be <var>currentNode</var>'s
+     <span>next sibling</span>.</p></li>
+
+     <li><p><span data-x="concept-node-remove">Remove</span> <var>currentNode</var>.</p></li>


How would you remove them all at once? That's not a primitive that we have. How do we account for changes here?

annevk · 2026-05-08T13:03:18Z

+
+        <ol>
+         <li><p>If <var>sibling</var> is not a <code>ProcessingInstruction</code> node, then
+         <span>continue</span>.</p></li>


So now we are doing nested traversals. I'm not sure that actually works as the descendant iterator will also just pick the next one. Presumably we want to skip over the descendants we are handling here?

This is not exactly "nested traversal". We reach the first matching PI and then sibling-traverse it, but after that we're done.
I double-checked this algorithm and I think it does the right thing... Can you be more specific if there is an issue here?

annevk · 2026-05-08T13:08:56Z

+        <p class="note">This is to support patching inside plain <code>template</code> elements or
+        those using <code data-x="attr-template-shadowrootmode">shadowrootmode</code>. Nested
+        patching is not supported, since in this case <var>scope</var>'s <span>template
+        contents</span> will be empty and <span>prepare content patching</span> will fail.</p>


"Plain" template contents are a DocumentFragment. This means you have a bunch of type errors as you exclude that earlier.

annevk · 2026-05-08T13:13:18Z

+        <p class="note">This is to support patching <code>head</code> with a <code>template</code>
+        inside <code>body</code>.</p>
+       </li>
+


We should have an assert here that scope is an Element or DocumentFragment.

Though also, can "the body element" be made to return null above with script?

If the document doesn't have a body then the condition after "otherwise" is never true. I think we can assert that the scope is an element or document fragment.

foolip added 2 commits October 22, 2025 16:33

Add declarative out-of-order streaming

6ec5ba3

Think out loud with TODOs and questions

50a4491

foolip changed the title ~~Add <template contentmethod declarative out-of-order streaming~~ Add <template contentmethod> for declarative out-of-order streaming Oct 22, 2025

foolip marked this pull request as draft October 22, 2025 15:05

noamr reviewed Oct 22, 2025

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

foolip added 3 commits October 23, 2025 19:00

Flesh things out more

97d3cfd

Let shadowrootmode take precedent over contentmethod

8739f8b

Add a note about scope's type

00872de

zcorpan added the topic: parser label Oct 28, 2025

zcorpan reviewed Oct 28, 2025

View reviewed changes

Comment thread source Outdated

foolip added 3 commits October 29, 2025 22:52

Fix incorrect method descriptions

d99f332

Define templat's content target element-or-null slot

5c43560

Flesh out a lot of details (some in the wrong place/order)

cec66b6

noamr mentioned this pull request Nov 6, 2025

WHATUP at TPAC 2025: agenda suggestions #11711

Closed

foolip added 2 commits November 7, 2025 19:29

Rewrite again to handle all known issues

ff83da1

Add an example

1d1af08

foolip marked this pull request as ready for review November 8, 2025 12:13

Refactors on a plane

911cd92

noamr reviewed Dec 4, 2025

View reviewed changes

Comment thread source Outdated

Drop contentmethod=replace and prepend

1e56dfb

foolip force-pushed the foolip/contentmethod branch from af700a0 to 1e56dfb Compare December 4, 2025 12:37

foolip added 4 commits December 4, 2025 14:16

Clarify purpose of body scope hoisting

e4946fc

Disallow patching of <script>

521f343

Introduce "content error" to make errors unrecoverable

f5a06b1

Fix TODOs and typos

5fe6778

foolip mentioned this pull request Mar 6, 2026

Support markers on shadow roots whatwg/dom#1456

Closed

5 tasks

Rewrite to <template for> with PIs

0dbaff6

foolip changed the title ~~Add <template contentmethod> for declarative out-of-order streaming~~ Add <template for> for declarative out-of-order streaming Mar 9, 2026

noamr reviewed Mar 9, 2026

View reviewed changes

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

Comment thread source Outdated

foolip added 6 commits March 9, 2026 16:13

split for on the first #

61d4ab1

Fix "find marker" algo bugs

3c7abb0

Add null check for end node

3382877

assert that start is not null

34f4e4a

Use template contents when scope is a template

168c4c8

Restore adjusted insertion location fixups for DSD

f5ff8d5

foolip mentioned this pull request Mar 9, 2026

Out of order HTML streaming ("patching") #11542

Open

noamr reviewed Mar 10, 2026

View reviewed changes

foolip added 2 commits March 12, 2026 11:40

Add note about nested <template for>

36ae3a5

Drop the marker attribute

862f5f2

noamr reviewed Mar 18, 2026

View reviewed changes

Comment thread source Outdated

Compare PI target case-sensitively

ce2772a

noamr reviewed Mar 18, 2026

View reviewed changes

Require <template for> to not be the empty string

59580a6

annevk reviewed May 8, 2026

View reviewed changes

foolip added 3 commits May 12, 2026 11:01

let be -> set to

b6e1da9

editorial fixes

c23b7b7

Define <template for> value validity

c16a640

noamr mentioned this pull request May 17, 2026

Add class & for aliases for className and htmlFor #9379

Open

noamr mentioned this pull request May 26, 2026

Out of order streaming with <template for> web-platform-dx/web-features#4073

Open

Jamesernator mentioned this pull request May 30, 2026

Should parse5 support each template insertion targeting behavior (e.g. declarative shadow dom, template for), or just a general mechanism which tree adapters hook into? inikulin/parse5#1773

Open

-        <p class="note">This is to support patching inside <code>template</code> elements.</p>
+        <p class="note">This is to support patching inside <code>template</code> elements. It
+        would work for normal templates or declarative shadow roots, however it effectively disallows
+        nested patches, as the <span>template contents</span> is separate from the <span>insertion
+        target</span></p>

Conversation

foolip commented Oct 22, 2025 • edited by pr-preview Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

foolip commented Nov 6, 2025

Uh oh!

noamr commented Nov 6, 2025

Uh oh!

foolip commented Nov 8, 2025

Uh oh!

noamr commented Nov 8, 2025

Uh oh!

foolip commented Nov 9, 2025

Uh oh!

noamr commented Nov 10, 2025

Uh oh!

noamr commented Nov 11, 2025

Uh oh!

foolip commented Nov 14, 2025

Uh oh!

foolip commented Nov 20, 2025

Uh oh!

Uh oh!

foolip commented Mar 9, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

noamr May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

foolip commented Oct 22, 2025 •

edited by pr-preview Bot

Loading

noamr May 11, 2026 •

edited

Loading