Ability to configure whether script elements should execute for setHTMLUnsafe()

[zcorpan]

What is the issue with the HTML Standard?

Currently innerHTML and insertAdjacentHTML() will not execute script elements because:

https://html.spec.whatwg.org/#script-processing-model:already-started-4 sets "already started" to true when the element is inserted into the temporary document during fragment parsing, and step 17 returns because scripting is disabled for that document. Then when the elements are inserted into the right place, "already started" is still true and https://html.spec.whatwg.org/#script-processing-model:already-started-3 returns.

Range.createContextualFragment() unsets the "already started" flag and therefore runs scripts: https://w3c.github.io/DOM-Parsing/#dom-range-createcontextualfragment (step 4).

In a previous meeting for Sanitizer API, we discussed this for setHTMLUnsafe() and the group's general agreement was that we should align with innerHTML by default but in the future we can allow a config to make script elements execute.

(This was originally filed at WICG/sanitizer-api#195 )

cc @whatwg/html-parser @mozfreddyb

[jakearchibald]

Take an article like https://jakearchibald.com/2025/animating-zooming/. It has little interactive examples throughout. Due to the simplicity, this is handled with inline snippets like:

<script>
  {
    const currentScript = document.currentScript;
    const demoContainer = currentScript.previousElementSibling;
    const buttonsContainer = demoContainer.querySelector('.demo-buttons');
    const zoomer = demoContainer.querySelector('.zoomer');

    const button = document.createElement('button');
    button.classList.add('btn');
    button.textContent = 'Toggle zoom';
    button.addEventListener('click', () => {
      zoomer.classList.toggle('zoom');
    });
    buttonsContainer.append(button);
  }
</script>

However, if I tried to make same-document navigations work on my site by updating the article content with setHTMLUnsafe() etc, these would fail.

It seems like, if we want to support this kind of simple content updating, we should have a way to parse HTML that's as-close-as-possible in behaviour to the document loading HTML parser.

[jakearchibald]

With createContextualFragment:

const range = document.createRange();
range.selectNode(document.body);

document.body.append(
  range.createContextualFragment(`
    <script>console.log('foo', [...document.body.children])<\/script>
    <script>console.log('bar', [...document.body.children])<\/script>
  `)
);

In each script execution, document.body.children contains both scripts, which is not quite like the document parser. Ideally the currently executing script should be the last child, since it's 'parser blocking'.

[Kruemelmann]

Hi @zcorpan ,
As you suggested in the issue, I have built an example project. I had the problem back then in the context of WebAssembly, but I came up with more use cases over the past few days when I was building the sample project.

Possible Use Cases for an insertAdjacentHTML() Flag to Control Script Execution

1. Performance Optimization when Inserting HTML

   • Without execution: Insert large HTML templates or UI components that contain scripts, but defer or skip their execution to improve rendering speed.
   • With execution: Dynamically load modules or widgets that should work immediately (e.g., a chart widget that brings its own script).

2. Security / XSS Scenarios

   • Default (no execution): Prevent scripts from running when inserting untrusted HTML from external sources or APIs.
   • Explicit enable: Allow scripts only for trusted HTML fragments, similar to a whitelisted module or widget.

3. Lazy Execution / Progressive Enhancement

   • Insert HTML containing scripts but keep them inactive initially.
   • Later activate them explicitly (re-insert or toggle execution) when user interaction requires it.

4. Templating & Reuse

   • Keep HTML snippets (with embedded scripts) as templates in the DOM without execution.
   • Reuse them by inserting with executeScripts: true in contexts where the scripts should actually run.

5. Testing & Debugging

   • Insert HTML with scripts but prevent execution to test DOM structure.
   • Useful for verifying markup correctness without triggering event handlers or side effects.

Hope it helps :)