Renewed HTML insertion & streaming methods

at a glance

why it exists

insertAdjacentHTML was designed in the IE era and has a string-enum position argument ("beforebegin", "afterend", etc.) that is error-prone and verbose. innerHTML replaces content but doesn't provide relative insertion. Neither accepts streams. This feature replaces both with ergonomic methods that follow the naming of the existing Element manipulation API and adds streaming variants for progressive server-rendered HTML.

positional insertion methods

These methods mirror the existing Node manipulation API but accept HTML strings instead of Node objects. Each parses the string in the context of the element's owner document.

streaming methods

Streaming variants accept a ReadableStream of HTML chunks and parse them progressively into the document, enabling low-latency rendering of server-streamed responses without JavaScript orchestration beyond kicking off the stream.

Error paths: the explainer does not yet define when or how these methods raise errors — its security-and-privacy questionnaire answers “It will.” One open question is whether positional insertion on an element with no parent should throw a hierarchy exception or fail silently the way before()/after() do. Until error behaviour is specified, verify it in the browser before shipping.

example

Perform positional HTML insertion or stream server-sent HTML chunks directly into an element:

// Old
container.insertAdjacentHTML("beforeend", "<li>New item</li>");

// New
container.setHTMLLast("<li>New item</li>");

Stream a fetch response into the page

const res = await fetch("/partial/comments");
const stream = res.body.pipeThrough(new TextDecoderStream());

// Stream comment HTML into #comments-container without JS parsing.
// Bare call: the return contract is unsettled (promise vs WritableStream) - do not
// rely on awaiting it until the API contract is established (see the syntax section).
document.getElementById("comments-container").streamHTMLLast(stream);

The full positional and streaming set

// Positional variants (string HTML)
item.setHTMLBefore('<li>before</li>');
item.setHTMLAfter('<li>after</li>');
list.setHTMLFirst('<li>first</li>');
item.setHTMLReplacing('<section>replaced</section>');

// Streaming variants accept a ReadableStream of HTML chunks. Their return contract is
// unsettled in the explainer (promise vs WritableStream), so the calls are shown bare -
// do not rely on awaiting them until the API contract is established.
item.streamHTMLBefore(beforeStream);
item.streamHTMLAfter(afterStream);
list.streamHTMLFirst(firstStream);
item.streamHTMLReplacing(replaceStream);

browser support

see also

• WICG/declarative-partial-updates — spec repository
• Out of order streaming — declarative (no-JS) streaming companion
• chromestatus: Renewed HTML insertion & streaming methods
• chromestatus: API record 5054329641893888
• chromestatus: milestone=148 listing
• Chromium Issue 491743369
• GoogleChromeLabs/html-setters-polyfill
• WPT results: domparsing/tentative
• chrome-platform-showcase: demos