Element.innerHTML - add info trusted types #40423

hamishwillee · 2025-07-18T07:04:26Z

This updates the following properties to explain how they are used with TrustedTypes:

This is in progress:

Add boilerplate
Add TT information, including the new exception and tinyfill
Restructured - this isn't to current templates. Need to move the guid-ish stuff either down as examples or up into description

This does not mention the sanitizer methods as alternatives since the setHTML() is not implemented anywhere, and the sanitizer in setHTMLUnsafe() is not yet implemented. We're in separate discussion on those and when they are in a release we can revisit.

Part of #37518 (tracking issue)

files/en-us/web/api/element/innerhtml/index.md

hamishwillee · 2025-07-18T07:05:25Z

files/en-us/web/api/element/innerhtml/index.md

@@ -79,15 +153,6 @@ document.documentElement.innerHTML = `<pre>${document.documentElement.innerHTML.
 )}</pre>`;
 ```

-#### Operational details


This is interesting I guess. But it doesn't actually matter. If it did/does it should be in the description part.

github-actions · 2025-07-18T07:06:25Z

Preview URLs

External URLs (3)

URL: /en-US/docs/Web/API/Element/innerHTML
Title: Element: innerHTML property

https://github.com/cure53/DOMPurify (1 time) (Note! This may be a new URL 👀)
https://research.securitum.com/dompurify-bypass-using-mxss/ (1 time) (Note! This may be a new URL 👀)

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

https://hacks.mozilla.org/2011/11/insertadjacenthtml-enables-faster-html-snippet-injection/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2025-07-21 07:07:10)

files/en-us/web/api/element/innerhtml/index.md

hamishwillee · 2025-07-21T05:27:20Z

FYI @lukewarlow @wbamberg - this is the trusted types update for Element.innerHTML. Luke, I've taken on board your comments about sanitizer not yet being implemented. I still mention the setHTMLUnsafe() because it allows set with shadow roots, but not as alternatives with sanitization. It should however be possible to graft that information on here quite easily.

All the examples use trustedHTML. This also shows the first live example use of the tinyfill in the docs. This is duplication with the main docs, but it feels very practical to me given the current state of trustedtypes.

hamishwillee · 2025-07-21T07:06:56Z

files/en-us/web/api/element/insertadjacenthtml/index.md

@@ -105,15 +119,35 @@ code {

 #### JavaScript

+```js hidden


Decided to hide the tinyfill in this case. Do you think it should be here. Or perhaps a note "if trusted types not supported you should add a tinyfill".

wbamberg

Just comments on innerHTML for now.

wbamberg · 2025-07-29T23:57:46Z

files/en-us/web/api/element/innerhtml/index.md

+Getting the property returns a string containing the HTML serialization of the element's descendants.

+Setting the value of `innerHTML` removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the assigned {{domxref("TrustedHTML")}} or string.


I think it might help some of the other discussion to be clearer about the types that this property can accept. As it stands, especially the "Setting the value" para starts with what it does, not what types it accepts, which turns out to be important of course for when we want to talk about trusted types.

Maybe something like:

Suggested change

Getting the property returns a string containing the HTML serialization of the element's descendants.

Setting the value of `innerHTML` removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the assigned {{domxref("TrustedHTML")}} or string.

Getting the property returns a string containing the HTML serialization of the element's descendants.

Setting the property accepts either a {{domxref("TrustedHTML")}} object or a string. It parses this value as HTML and replaces all the element's descendants with the result.

wbamberg · 2025-07-29T23:58:23Z

files/en-us/web/api/element/innerhtml/index.md

 When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`.
+Note that {{htmlelement("script")}} elements in the assigned value are injected but not executed.


Maybe better in the security section, where it is mentioned? Anyway, seems a poor fit for "Value".

wbamberg · 2025-07-29T23:58:47Z

files/en-us/web/api/element/innerhtml/index.md

+
+Shadow roots are dropped from the serialized and injected HTML.


Also doesn't seem a good fit for "Value", and is already covered in "Description".

wbamberg · 2025-07-30T00:32:33Z

files/en-us/web/api/element/innerhtml/index.md

+The serialization of the DOM tree read from the property does not include {{glossary("shadow tree", "shadow roots")}} — if you want to get a HTML string that includes shadow roots, you must instead use the {{domxref("Element.getHTML()")}} or {{domxref("ShadowRoot.getHTML()")}} methods.
+
+Similarly, when setting element content using `innerHTML`, the HTML string is parsed into DOM elements that do not contain shadow roots.
+So for example [`<template>`](/en-US/docs/Web/HTML/Reference/Elements/template) is parsed into as {{domxref("HTMLTemplateElement")}}, whether or not the [`shadowrootmode`](/en-US/docs/Web/HTML/Reference/Elements/template#shadowrootmode) attribute is specified.
+In order to set an element's contents from an HTML string that includes declarative shadow roots, you must instead use {{domxref("Element.setHTMLUnsafe()")}} or {{domxref("ShadowRoot.setHTMLUnsafe()")}}.


Because this is about a very distinct aspect of innerHTML, I would have these two paragraphs under an H3 like "Shadow DOM considerations" or something, and move it after the para about "Note that some browsers...".

You might also consider moving "Note that some browsers..." into "Security considerations", maybe.

wbamberg · 2025-07-30T00:33:20Z

files/en-us/web/api/element/innerhtml/index.md

+
+You can mitigate these issues by always assigning {{domxref("TrustedHTML")}} objects instead of strings, and [enforcing trusted type](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) using the [`require-trusted-types-for`](/en-US/docs/Web/HTTP/Reference/Headers/Content-Security-Policy/require-trusted-types-for) CSP directive.
+This ensures that the input is passed through a transformation function, which has the chance to [sanitize](/en-US/docs/Web/Security/Attacks/XSS#sanitization) the input to remove potentially dangerous markup before it is injected.
+This is demonstrated in the following sections.


This is unclear. Which of the following sections demonstrate this? As a reader I want a direct link to a concrete example of this.

wbamberg · 2025-07-30T18:52:52Z

files/en-us/web/api/element/innerhtml/index.md

-This is then wrapped in a {{HTMLElement("pre")}} element.
-Then the value of `innerHTML` is changed to this new string.
-As a result, the document contents are replaced with a display of the page's entire source code.
+Next create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createHTML", "createHTML()")}} for transforming an input string into {{domxref("TrustedHTML")}} instances.


Suggested change

Next create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createHTML", "createHTML()")}} for transforming an input string into {{domxref("TrustedHTML")}} instances.

Next we create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createHTML", "createHTML()")}} for transforming an input string into {{domxref("TrustedHTML")}} instances.

Very pedantic, but this started "first we" so perhaps "next we" afterwards? Just "next" implicitly changes it from first-person to second.

wbamberg · 2025-07-30T18:53:14Z

files/en-us/web/api/element/innerhtml/index.md

 ```

-#### Operational details
+Then use this `policy` object to create a `TrustedHTML` object from the potentially unsafe input string, and assign the result to the element:


Suggested change

Then use this `policy` object to create a `TrustedHTML` object from the potentially unsafe input string, and assign the result to the element:

Then we use this `policy` object to create a `TrustedHTML` object from the potentially unsafe input string, and assign the result to the element:

wbamberg · 2025-07-30T18:56:14Z

files/en-us/web/api/element/innerhtml/index.md

-</ul>
+```js
+// Create a TrustedHTML instance using the policy
+document.body.textContent = policy.createHTML(policy.createHTML(""));


Is this supposed to be assigning to textContent?

wbamberg · 2025-07-30T18:58:46Z

files/en-us/web/api/element/innerhtml/index.md

 ```

-#### JavaScript
+Note that in this case we're setting the element to an empty string, which we know is safe.
+If we weren't [enforcing trusted types](/en-US/docs/Web/API/Trusted_Types_API#using_a_csp_to_enforce_trusted_types) we could instead directly assign the empty string:


I'm not sure we should encourage this. AIUI, if we don't enforce the use of trusted types, we lose a lot of the protection they offer (because you don't know any more whether somewhere in your codebase you might be unsafe).

So I would omit this.

wbamberg · 2025-07-30T19:04:05Z

files/en-us/web/api/element/innerhtml/index.md

 ```

-Please note that using `innerHTML` to append HTML elements (e.g., `el.innerHTML += "<a href='…'>link</a>"`) will result in the removal of any previously set event listeners.
-That is, after you append any HTML element that way you won't be able to listen to the previously set event listeners.
+### Logging messages using innerHTML


Is this example worth keeping? Is this a pattern we want to encourage, versus explicitly creating the DOM elements to put in the log?

and I also wonder, is it a good idea to recommend people to define a no-op TT policy? To what extent does that open up a hole in the whole thing?

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Jul 18, 2025

github-actions bot reviewed Jul 18, 2025

View reviewed changes

files/en-us/web/api/element/innerhtml/index.md Outdated Show resolved Hide resolved

hamishwillee commented Jul 18, 2025

View reviewed changes

hamishwillee mentioned this pull request Jul 18, 2025

[WebAPI] Implement Trusted Types support for document.write()/document.writeln() #37518

Open

11 tasks

hamishwillee commented Jul 20, 2025

View reviewed changes

files/en-us/web/api/element/innerhtml/index.md Outdated Show resolved Hide resolved

Element.innerHTML - add info trusted types

cfaddcf

hamishwillee force-pushed the element-innerhtml_tt branch from 24677d9 to cfaddcf Compare July 21, 2025 05:20

hamishwillee marked this pull request as ready for review July 21, 2025 05:22

hamishwillee requested a review from a team as a code owner July 21, 2025 05:22

hamishwillee requested review from sideshowbarker and wbamberg and removed request for a team July 21, 2025 05:22

sideshowbarker removed their request for review July 21, 2025 06:06

Element.insertAdjacentHTML

3ab8c5c

hamishwillee commented Jul 21, 2025

View reviewed changes

wbamberg reviewed Jul 30, 2025

View reviewed changes

		Getting the property returns a string containing the HTML serialization of the element's descendants.

		Setting the value of `innerHTML` removes all of the element's descendants and replaces them with nodes constructed by parsing the HTML given in the assigned {{domxref("TrustedHTML")}} or string.

		When set to the `null` value, that `null` value is converted to the empty string (`""`), so `elt.innerHTML = null` is equivalent to `elt.innerHTML = ""`.
		Note that {{htmlelement("script")}} elements in the assigned value are injected but not executed.


		Shadow roots are dropped from the serialized and injected HTML.

	Next create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createHTML", "createHTML()")}} for transforming an input string into {{domxref("TrustedHTML")}} instances.
	Next we create a {{domxref("TrustedTypePolicy")}} that defines a {{domxref("TrustedTypePolicy/createHTML", "createHTML()")}} for transforming an input string into {{domxref("TrustedHTML")}} instances.

	Then use this `policy` object to create a `TrustedHTML` object from the potentially unsafe input string, and assign the result to the element:
	Then we use this `policy` object to create a `TrustedHTML` object from the potentially unsafe input string, and assign the result to the element:

Element.innerHTML - add info trusted types #40423

Are you sure you want to change the base?

Element.innerHTML - add info trusted types #40423

Conversation

hamishwillee commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

hamishwillee commented Jul 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wbamberg left a comment

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!

wbamberg Jul 30, 2025 • 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!

Uh oh!

hamishwillee commented Jul 18, 2025 •

edited

Loading

github-actions bot commented Jul 18, 2025 •

edited

Loading

wbamberg Jul 30, 2025 •

edited

Loading