New HTML setters by tunetheweb · Pull Request #46127 · mdn/content

tunetheweb · 2026-10-13T14:05:35Z

Description

This documents the static HTML setters as detailed here:
https://developer.chrome.com/docs/web-platform/declarative-partial-updates#renewed_html_insertion_and_streaming_methods

I have excluded the streaming APIs (will follow up with that in a future PR), and also excluded TrustedParserOptions (will follow up with that in a future PR).

This is quite a big PR, but most of it is copied and pasted from the existing setHTML() and setHMTLUnsafe() docs with minor updates.

There is a lot of duplication here though so I'm open to ideas of how to structure this better if we want minimal docs in ShadowRoot and CharacterData versions of these docs and leave the main docs to just the Element versions of these APIs and reference it? Or alternatively we could leave most of the docs in setHTML, setHTMLUnsafe and reference those from the other docs?

Motivation

These were released in Chrome 157 (they were available behind a flag before that) and have also been merged in to the HTML Living standard (whatwg/html#12753)

Additional details

Docs: https://developer.chrome.com/docs/web-platform/declarative-partial-updates#renewed_html_insertion_and_streaming_methods
Chrome Status: https://chromestatus.com/feature/5054329641893888
Spec PR: whatwg/html#12753

Related issues and pull requests

They were already added to BCD in mdn/browser-compat-data#30328 and a follow up with spec links mdn/browser-compat-data#30874

github-actions · 2026-10-13T14:07:24Z

Preview URLs (29 pages)

External URLs (11)

URL: /en-US/docs/Glossary/Sanitize
Title: sanitize

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/CharacterData/afterHTMLUnsafe
Title: CharacterData: afterHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/CharacterData/beforeHTMLUnsafe
Title: CharacterData: beforeHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/CharacterData/replaceWithHTMLUnsafe
Title: CharacterData: replaceWithHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Element/afterHTMLUnsafe
Title: Element: afterHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Element/appendHTMLUnsafe
Title: Element: appendHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Element/beforeHTMLUnsafe
Title: Element: beforeHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Element/prependHTMLUnsafe
Title: Element: prependHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/Element/replaceWithHTMLUnsafe
Title: Element: replaceWithHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/ShadowRoot/appendHTMLUnsafe
Title: ShadowRoot: appendHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

URL: /en-US/docs/Web/API/ShadowRoot/prependHTMLUnsafe
Title: ShadowRoot: prependHTMLUnsafe() method

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2026-11-09 22:54:01)

…than helpful

wbamberg · 2026-10-14T09:34:58Z

+The **`afterHTML()`** method of the {{domxref("CharacterData")}} interface provides an XSS-safe method to parse and sanitize a string of HTML and insert it into the DOM after the existing character data.
+
+The method removes any elements and attributes that are considered XSS-unsafe, even if allowed by a passed sanitizer.
+Notably, the following elements are always removed: {{HTMLElement("script")}}, {{HTMLElement("frame")}}, {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, {{HTMLElement("object")}}, {{SVGElement("use")}}, and event handler attributes.


This is a lot of duplication. I see this was added in #41695, in response to #41655, but I'm not sure that was a good choice. Am I right in thinking that the "elements that are always removed" are the subset of the ones in https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration listed in the first bullet as "Those that are known to be XSS-unsafe:"? If so this list omits <base>, is there a reason for this?

It would be better IMO to adapt https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration so it gives us a clear place to link "XSS-unsafe items", and link to it.

Also attributes are not elements, so "the following elements are always removed: ... and event handler attributes." is wrong.

This is a lot of duplication.

Yeah I said "There is a lot of duplication here though so I'm open to ideas of how to structure this better" in this initial PR comment because of things like this.

Am I right in thinking that the "elements that are always removed" are the subset of the ones in https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration listed in the first bullet as "Those that are known to be XSS-unsafe:"? If so this list omits , is there a reason for this?

I think that's correct. And no good reason that <base> isn't included, other than I guess it's not a common an element and I think the "Notably" here is meant to indicate this is a subset rather than a complete list. But agree it could be clearer.

I'm torn between linking, and avoiding readers having to link off to another page just to grasp the concepts.

Also attributes are not elements, so "the following elements are always removed: ... and event handler attributes." is wrong.

This would probably better worded as "and similarly for unsafe event handler attributes (for example onclick)". Happy to make that change across the board if we keep this text here.

Changed it to this everywhere:

The method removes any elements and attributes that are considered XSS-unsafe, even if allowed by a passed sanitizer.
Notably, the following elements are always removed: {{HTMLElement("script")}}, {{HTMLElement("frame")}}, {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, {{HTMLElement("object")}}, {{HTMLElement("base")}}, {{SVGElement("use")}}, as well event handler content attributes (for example, onclick, onload, onerror and so forth). See default sanitizer configuration for more information.

I'm torn between linking, and avoiding readers having to link off to another page just to grasp the concepts.

I think linking to a single source is better for readers, because they know, for sure, what the concept means. As you say, "Notably" is kind of a weasel word: it suggests "there might be other things in the definition" and as a reader of a reference page, I want to know: what are they?

I was hoping adding the link would satisfy your concern here.

There's lots of nuance and detail on the https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration but I think the important point (that most developers will care about) is provided in this sentence. I'm not sure excluding this completely and only linking to really long page with complete details is better.

So I guess what I'm saying is that "Notably" here is a a high-level summary of the main points that devs need to care about, rather than a weasel word trying to say something without really saying anything. And the link is then provided for those that do want more detail.

Does that persuade you at all?

There's lots of nuance and detail on the https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Default_sanitizer_configuration

Yes, there is, but that's because, according to the page itself, it's not just about XSS-unsafe:

This configuration removes the following sorts of items:

Those that are known to be XSS-unsafe:

<base>, <embed>, <frame>, <iframe>, <object>, <script>, and <use>.

All event handler content attributes, such as onafterprint, onbeforeinput, and so on.

...

...

Note: Calling Sanitizer.removeUnsafe(), or passing a custom sanitizer to the safe sanitization method, only removes the XSS-unsafe items. It does not remove the additional items, comments, and data-* attributes.

That's why I didn't suggest just linking to the page, but adapting it so it gives us a clear place to link "XSS-unsafe items", and linking to that place, so we can have one concise definition of it that everyone uses.

So I guess what I'm saying is that "Notably" here is a a high-level summary of the main points that devs need to care about, rather than a weasel word trying to say something without really saying anything.

I meant "weasel word" just in a technical sense not pejoratively, but I'm sorry if it seemed like that. But now you added <base> to the list, this doesn't seem to be a summary of what's in the page, but just the same thing. The page doesn't add more detail about XSS unsafe, AFAICS.

FWIW I think https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API/Using_the_HTML_Sanitizer_API also suffers from not having a definitive place to link "XSS unsafe":

For example, the following code will remove all XSS-unsafe elements and attributes in the input string (in this case the <script> element), along with any elements that aren't permitted as children of the target element by the HTML specification:

I think you're right. But also a little worried about defining this when I'm not 100% sure I'd be right about it! It's kinda an existing issue and orthogonal to documenting these new APIs that I'm trying to do here.

I think this is the official definition: https://html.spec.whatwg.org/multipage/dynamic-markup-insertion.html#remove-unsafe but not confident enough to translate that spec language to MDN. Or even to understand it fully truth be told! I hate the HTML spec FWIW :-)

tunetheweb · 2026-11-02T10:44:55Z

Any more thoughts on this one @wbamberg ? Appreciate it's a big one and will take some time to review!

wbamberg · 2026-11-02T16:22:05Z

Sorry @tunetheweb , I will take a look today.

wbamberg · 2026-11-02T19:25:38Z

I haven't looked at everything here yet but I think it's worth making some high-level choices before getting into all the details.

I've looked fairly quickly at all the non-unsafe setter pages, and I think we should:

update the HTML Sanitizer API guides to talk about safe and unsafe HTML setters, probably as some version of the first two sections of Using the HTML Sanitizer API, and ensure this covers everything that's currently duplicated in the Description section of these setter pages.
update the Description sections in this PR to link there.

wbamberg

Sorry this is a little chaotic. I had a few more comments for now, some of which I made before but never submitted apparently.

wbamberg · 2026-11-02T19:44:37Z

+The **`afterHTML()`** method of the {{domxref("CharacterData")}} interface provides an XSS-safe method to parse and sanitize a string of HTML and insert it into the DOM after the existing character data.
+
+The method removes any elements and attributes that are considered XSS-unsafe, even if allowed by a passed sanitizer.
+Notably, the following elements are always removed: {{HTMLElement("script")}}, {{HTMLElement("frame")}}, {{HTMLElement("iframe")}}, {{HTMLElement("embed")}}, {{HTMLElement("object")}}, {{SVGElement("use")}}, and event handler attributes.


I'm torn between linking, and avoiding readers having to link off to another page just to grasp the concepts.

I think linking to a single source is better for readers, because they know, for sure, what the concept means. As you say, "Notably" is kind of a weasel word: it suggests "there might be other things in the definition" and as a reader of a reference page, I want to know: what are they?

hamishwillee · 2026-11-02T23:09:18Z

update the HTML Sanitizer API guides to talk about safe and unsafe HTML setters, probably as some version of the first two sections of Using the HTML Sanitizer API, and ensure this covers everything that's currently duplicated in the Description section of these setter pages.

update the Description sections in this PR to link there.

FWIW the existing intro to safe vs unsafe methods is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#sanitization_methods ... but where you might also update (for cross linking) is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#extensions_to_other_interfaces

tunetheweb · 2026-11-05T20:21:23Z

FWIW the existing intro to safe vs unsafe methods is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#sanitization_methods ... but where you might also update (for cross linking) is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#extensions_to_other_interfaces

I've added these methods to the first section.

I'm not sure the section section adds much at all beyond that. And I wouldn't see these as extensions to those interfaces per se. Especially the "safe" versions where the Sanitzier API is no so much an "extension" as an integral part of this API! Now it's true that Safari has shipped setHTMLUnsafe without the Sanitizer API so it's kind of an extension to that, but even that's a reach IMHO. So I've deleted this section from the HTML Sanitizer Docs in this PR.

tunetheweb · 2026-11-05T20:53:52Z

update the HTML Sanitizer API guides to talk about safe and unsafe HTML setters, probably as some version of the first two sections of Using the HTML Sanitizer API, and ensure this covers everything that's currently duplicated in the Description section of these setter pages.

I think this is already covered? Though I've tweaked it a little. And ensured all the new methods are listed too. Though technically they are not really part of the Sanitizer API, but it's a bit blurry anyway since they are all part of HTML rather than a separate "Sanitizer API" spec.

update the Description sections in this PR to link there.

I've added a link to the Sanitizer API docs but I've left most of the text in place as well as this. Most of the duplicated text talks about config to these methods, rather than specific sanitizer options. So not sure this text should be replaced with links to the Sanitizer API. Re-reading it I'm not sure it's that much duplicated text. And if what is duplicated even is a bad thing. But open to more suggestions here...

wbamberg · 2026-11-05T23:30:38Z

FWIW the existing intro to safe vs unsafe methods is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#sanitization_methods ... but where you might also update (for cross linking) is https://developer.mozilla.org/en-US/docs/Web/API/HTML_Sanitizer_API#extensions_to_other_interfaces

I've added these methods to the first section.

I'm not sure the section section adds much at all beyond that. And I wouldn't see these as extensions to those interfaces per se. Especially the "safe" versions where the Sanitzier API is no so much an "extension" as an integral part of this API! Now it's true that Safari has shipped setHTMLUnsafe without the Sanitizer API so it's kind of an extension to that, but even that's a reach IMHO. So I've deleted this section from the HTML Sanitizer Docs in this PR.

"extensions to other interfaces" is how we capture the situation where "APIs" (aka specifications) extend existing interfaces, rather than cases where they define completely new interfaces. Here, the specification defines a couple of new interfaces, Santitizer and SantitizerConfig, and also adds a bunch of methods to other interfaces, such as Element. We call those methods extensions to other interfaces. This is how we're able to present an API as a properly unitary thing.

tunetheweb · 2026-11-06T10:06:36Z

"extensions to other interfaces" is how we capture the situation where "APIs" (aka specifications) extend existing interfaces, rather than cases where they define completely new interfaces. Here, the specification defines a couple of new interfaces, Santitizer and SantitizerConfig, and also adds a bunch of methods to other interfaces, such as Element. We call those methods extensions to other interfaces. This is how we're able to present an API as a properly unitary thing.

Yeah I get that, and I think that makes sense when an external spec extends another spec. In this case it's a little greyer IMHO as both are in the same spec (HTML). Though admittedly in different sections 8.5 and 8.6, though they are right beside each other and all under section 8.

Plus the "safe" methods (and arguably the "unsafe" ones too - see previous comment) don't make any sense without this — you can't have safe methods without sanitizer, so it's not like they existed first, and then the sanitizer API extended them. One view is that they are all part of the sanitizer — in fact @ddbeck and I had pretty much this discussion on the web-features PR for the HTML setters.

IMHO the Sanitizer API is part of HTML now, and keeping this "extensions to other interfaces" section when it doesn't say much beyond the "sanitization methods: section is not adding any value, and making this page much longer than it needs to be. It's also questionable whether it makes sense since it only lists methods that are already listed as methods of this API in the left hand nav. And all this will only get worse once we add these 20 APIs to this section (and another 20 when we document the streaming versions that just landed in HTML yesterday).

We wouldn't say Node or Element, or any other core concept, extends other interfaces.

github-actions · 2026-11-09T22:46:43Z

This pull request has merge conflicts that must be resolved before it can be merged.

tunetheweb added 6 commits October 13, 2026 14:09

Add remaining element methods

0cc6357

Merge branch 'main' into html-setters

a01a91a

Add CharacterData APIs

e94dda7

Add ShadowRoot

6ac5bc2

Misc fixes

c9eec1b

TypeError

0698bf9

tunetheweb requested a review from a team as a code owner October 13, 2026 14:05

tunetheweb requested review from wbamberg and removed request for a team October 13, 2026 14:05

github-actions Bot added Content:WebAPI Web API docs size/xl [PR only] >1000 LoC changed labels Oct 13, 2026

tunetheweb added 3 commits October 13, 2026 15:09

Add tabke to setHTML and setHTMLUnsafe

437ef92

Remove incorrect CharacterData references

d5b66a6

Fix without runScripts -> with runScripts

bb5f7e3

tunetheweb changed the title ~~Html setters~~ New HTML setters Oct 13, 2026

tunetheweb added 4 commits October 13, 2026 17:45

AI Feedback

0bf2f78

More AI fixes

5546158

More AI review feedback

c8afea4

Yet more AI feedback

a581f06

tunetheweb requested a review from a team as a code owner October 13, 2026 19:55

github-actions Bot added the Content:HTML Hypertext Markup Language docs label Oct 13, 2026

tunetheweb added 3 commits October 13, 2026 21:07

More AI feedback

135f3ad

Final AI comment (for now)

7a8aedb

Remove all references to setHTML and setHTMLUnsafe as more confusing …

e059b1d

…than helpful

wbamberg reviewed Oct 14, 2026

View reviewed changes

tunetheweb added 3 commits October 14, 2026 19:09

Feedback from Noam and Will

03184e2

Fix <base> macro

aeb656b

Merge branch 'main' into html-setters

96757b2

wbamberg reviewed Nov 2, 2026

View reviewed changes

Review feedback

1d8918f

tunetheweb requested a review from a team as a code owner November 5, 2026 20:21

tunetheweb requested review from chrisdavidmills and removed request for a team November 5, 2026 20:21

github-actions Bot added the Content:Glossary Glossary entries label Nov 5, 2026

More tweaks

610a9aa

tunetheweb requested a review from wbamberg November 5, 2026 20:54

Merge branch 'main' into html-setters

1b6fa51

hamishwillee mentioned this pull request Nov 5, 2026

Document sanitization during HTML parsing #46211

Open

github-actions Bot added the merge conflicts 🚧 [PR only] label Nov 9, 2026

Merge branch 'main' into html-setters

8e704b9

github-actions Bot removed the merge conflicts 🚧 [PR only] label Nov 9, 2026

Merge branch 'main' into html-setters

006b69f

Conversation

tunetheweb commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Related issues and pull requests

Uh oh!

github-actions Bot commented Oct 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tunetheweb Oct 14, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tunetheweb commented Nov 2, 2026

Uh oh!

wbamberg commented Nov 2, 2026

Uh oh!

wbamberg commented Nov 2, 2026

Uh oh!

wbamberg left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hamishwillee commented Nov 2, 2026

Uh oh!

tunetheweb commented Nov 5, 2026

Uh oh!

tunetheweb commented Nov 5, 2026

Uh oh!

wbamberg commented Nov 5, 2026

Uh oh!

tunetheweb commented Nov 6, 2026

Uh oh!

github-actions Bot commented Nov 9, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tunetheweb commented Oct 13, 2026 •

edited

Loading

github-actions Bot commented Oct 13, 2026 •

edited

Loading

tunetheweb Oct 14, 2026 •

edited

Loading