Intent to Ship: Renewed HTML insertion&streaming methods

[Chromestatus]

Contact emails

nrose...@chromium.org, foo...@chromium.org

Explainer

https://github.com/WICG/declarative-partial-updates/blob/main/dynamic-markup-revamped-explainer.md

Specification

https://github.com/WICG/declarative-partial-updates/blob/main/dynamic-markup-revamped-explainer.md#resulting-api

Summary

Expose multiple HTML setting methods that provide a coherent story for dynamically inserting markup into an existing document. - Positional methods (before/after/append/prepend/replaceWith) that take HTML as argument, effectively replacing insertAdjacentHTML. - Streaming methods (stream{Append}HTML{Unsafe}) which return a WritableStream - Passing {runScripts} as part of SetHTMLUnsafeOptions, mimicking createContextualFragment behavior. - Supporting createParserOptions in trusted types, allowing trusted types to override scripting mode and sanitizer.

Blink component

Blink>HTML>Parser

Web Feature ID

Missing feature

Motivation

Updating HTML dynamically from script has multiple disjointed API, each with its own subtle differences. Developers can partially update an element using insertAdjacentHTML, use sanitizer with setHTML, execute scripts with createContextualFragment, stream with detached documents. This can be confusing and frustrating to web developers, as well as create bugs or security issues if the differences are not well understood. This change replaces those with a coherent set of methods and arguments, that use the same settings (sanitizer/runScripts) with different variants (where to insert the HTML, stream/one-shot, safe/unsafe) as well as the same support in trusted types.

Initial public proposal

https://github.com/whatwg/html/issues/11669

TAG review

No information provided

TAG review status

Issues addressed

Goals for experimentation

None

Risks

Interoperability and Compatibility

See "anticipated spec changes". Because this is not fully standardized yet, there is some risk that some of the API will change between shipping and landing the standards change. Note that the proposed API was up for scrutiny for almost a year and hasn't gone through substantial changes.

Gecko: No signal (https://github.com/mozilla/standards-positions/issues/1370) (It's in "suggests positive" state)

WebKit: No signal (https://github.com/WebKit/standards-positions/issues/629) Note: WebKit folks have been active in the feature's design, despite not filing an official positive position yet.

Web developers: Positive (https://github.com/whatwg/html/issues/2142) See also https://github.com/whatwg/html/issues/10122

Other signals:

Security

Since this is about dynamic markup insertion, XSS needs to be carefully handled, and specifically integration with the sanitizer and trusted types. This has been a major design consideration.

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

No information provided

Debuggability

No information provided

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

Yes
https://wpt.fyi/results/domparsing/tentative?label=master&label=experimental&aligned

Flag name on about://flags

No information provided

Finch feature name

NewHTMLSettingMethods

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

False

Tracking bug

https://issues.chromium.org/issues/491743369

Adoption plan

A fully functional polyfill is already available at https://github.com/GoogleChromeLabs/html-setters-polyfill

Estimated milestones

Shipping on desktop	152
DevTrial on desktop	148
Shipping on Android	152
DevTrial on Android	148
Shipping on WebView	152

Anticipated spec changes

Open questions about a feature may be a source of future web compat or interop issues. Please list open issues (e.g. links to known github issues in the project for the feature specification) whose resolution may introduce web compat/interop risk (e.g., changing to naming or structure of the API in a non-backward-compatible way).

Nothing, I hope, but this is in the process of being upstreamed. So it's possible that some changes will be made after shipping. The comments on this is in recent weeks were quite on the cosmetic side, around the trusted-types integration.

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5054329641893888?gate=5996320374521856

This intent message was generated by Chrome Platform Status.

[Noam Rosenthal]

Two followup notes:
- We (as in Barry) have filed for a new Web Feature ID (https://github.com/web-platform-dx/web-features/issues/4117)
- The standardization upstreaming is tracked in this meta-issue: https://github.com/whatwg/html/issues/11669.
  It contains 5 sub-issues: one has landed, two have pending PRs, and the rest are waiting on those pending items.

  The PRs for this feature are stacked at the request of the reviewers.

[Dan Clark]

Thanks for working to make this into a consistent API surface!

This seems like something the TAG should have a chance to look at, would you mind filing a TAG review?

After scanning through https://github.com/whatwg/html/issues/11669 and the sub-issues I'm still uncertain on where we're at with the state of the spec work. You mentioned that the PRs are stacked per reviewer request and some are still waiting, but does complete spec text exist somewhere for all of these APIs? Or does some still need to be written, pending completion of earlier PRs? For spec PRs still open, what needs to happen for them to land?

Thanks,

Dan

[Noam Rosenthal]

On Mon, Jul 20, 2026 at 8:03 PM 'Dan Clark' via blink-dev <blin...@chromium.org> wrote:
>
> Thanks for working to make this into a consistent API surface!
>
> This seems like something the TAG should have a chance to look at, would you mind filing a TAG review?

This was discussed at part of out-of-order streaming before it was split out to a separate feature
https://github.com/w3ctag/design-reviews/issues/1134#issuecomment-3357614978 (your own comment :))
I've read that discussion as a go ahead to continue working on the details at WHATWG, but I'm happy to interpret it differently.

There was not much change to the API since that discussion, perhahps some nits around how this works with trusted types.

> After scanning through https://github.com/whatwg/html/issues/11669 and the sub-issues I'm still uncertain on where we're at with the state of the spec work. You mentioned that the PRs are stacked per reviewer request and some are still waiting, but does complete spec text exist somewhere for all of these APIs? Or does some still need to be written, pending completion of earlier PRs? For spec PRs still open, what needs to happen for them to land?

There are two HTML PRs waiting to be merged.
https://github.com/whatwg/html/pull/12583 (trusted types support)
https://github.com/whatwg/html/pull/12645 (sanitize while parsing)

On top of them there are going to be two PRs. Draft versions of both exist in isolation but they would all need to be rebased on top of the stack:
https://github.com/whatwg/html/pull/12528 (positional methods to replace insertAdjacentHTML)
https://github.com/whatwg/html/pull/11631 (streamHTML*)

Nothing in particular is preventing these PRs from merging, apart from the HTML standard editors' workload (and summer holidays).

As always, unforeseen issues can arise during the review.

Waiting for more upstreaming is one reasonable decision, shipping and adjusting later if needed is also a possible one.

I'm laying out the trade offs here and we can all make a decision :)