Lorixen.
EN

Trusted Types: stopping DOM XSS in your web app

Short answer: Trusted Types is a browser feature that stops your own front-end code from passing raw strings into dangerous DOM functions such as innerHTML, which is where DOM-based cross-site scripting (XSS) usually starts. You switch it on with a Content-Security-Policy directive, require-trusted-types-for 'script', and then route any HTML you genuinely need to insert through a small named policy that sanitises it. Start in report-only mode, fix what the reports show, then enforce.

The problem it solves

Most XSS discussions focus on the server: escape output in templates and you're safe. Modern business sites and web apps, though, build a lot of their page in the browser. A product configurator, a dashboard widget, a search box that echoes the query, a chat panel that renders messages: each of these takes data and writes it into the page with JavaScript.

MDN describes the risky functions as injection sinks. HTML sinks, such as Element.innerHTML or document.write(), interpret their input as HTML, so a string containing a <script> tag or an event handler attribute can run code. There are also JavaScript sinks (such as eval()) and script-URL sinks (such as setting a script element's src).

DOM XSS happens when untrusted data, perhaps from the URL, a third-party API or a user's own profile field, reaches one of those sinks without being cleaned.

Trusted Types changes the rules. Once enforced, the browser refuses plain strings at those sinks and throws a TypeError. Only special typed objects (TrustedHTML, TrustedScript and TrustedScriptURL) are accepted, and those can only be created by policies you define. The dangerous places in your code shrink from "every line that touches the DOM" to "the handful of policies", which are far easier to review.

Browser support in late 2026

MDN marks the Trusted Types API as Baseline 2026, newly available since February 2026, meaning it works in the latest versions of the major browsers. Older browsers simply ignore the directive. You should still keep your other XSS defences, such as template escaping and a sensible Content Security Policy.

How the pieces fit together

There are three parts.

1. The enforcement directive. In your CSP header you add:

Content-Security-Policy: require-trusted-types-for 'script'

With this set, MDN notes that passing strings into injection sinks results in a TypeError.

2. Policies. In JavaScript, you create a named policy that turns input into a trusted object. MDN's example pairs it with the DOMPurify sanitiser:

const policy = trustedTypes.createPolicy("my-policy", {
  createHTML: (input) => DOMPurify.sanitize(input),
});
element.innerHTML = policy.createHTML(userInput);

The policy is the one place where you decide how HTML is cleaned. Everything else in the codebase must go through it.

3. The allow-list of policy names. A second CSP directive, trusted-types, controls which policy names your code may create. For example, trusted-types my-policy allows only that name. This stops a third-party script, or an attacker, from quietly creating its own permissive policy. The directive also accepts 'none' and 'allow-duplicates' if you need them.

Rolling it out without breaking the site

Switching straight to enforcement on a live site is risky, because libraries and old code that write strings to sinks will start throwing errors. A gentler order works better.

Step 1: Report only. Send the directive in a Content-Security-Policy-Report-Only header with a reporting endpoint. The browser lets everything run but reports each place where a string hit a sink. The W3C specification's own test suite covers report-only behaviour, so this is an expected mode, not a hack.

Step 2: Read the reports and group them. You'll usually find three kinds of violation:

  • Your own code using innerHTML where textContent would do. If you're inserting plain text, use a text API and no policy is needed.
  • Code that genuinely needs HTML, such as rendering formatted help articles or rich product descriptions. Route these through your sanitising policy.
  • Third-party scripts, such as chat widgets, A/B testing tools or tag managers, that write HTML themselves. Check whether the vendor documents Trusted Types support; if not, you may need a carefully written default policy, or to reconsider the script.

Step 3: Consider a default policy as a bridge. MDN explains that you can define a policy named default. When a string reaches a sink, the browser passes it to the default policy instead of throwing. Treat this as a temporary safety net that logs and sanitises, so you can find leftover code paths. Don't make it a permanent "allow everything" policy, or you lose the benefit.

Step 4: Enforce. Once reports are quiet for a reasonable period across your main user journeys, move the directive into the enforcing Content-Security-Policy header. Keep the reporting endpoint so new violations are visible after future releases.

What to watch out for

  • Frameworks. Many front-end frameworks already avoid raw HTML sinks by default, but escape hatches exist, the ones with names that include words like "dangerously" or "unsafe". Search your codebase for them first; they're your likely violations.
  • Policy sprawl. Keep one or two policies with clear owners. Ten policies written by different developers recreate the original problem.
  • Sanitiser configuration. A policy is only as safe as the function inside it. A createHTML that returns the input unchanged satisfies the browser and protects nothing.
  • Script URLs. If your code loads scripts dynamically, those assignments need a createScriptURL policy that checks the URL against an allow-list of your own domains.

A worked example

Take a hypothetical Manchester events company whose booking app shows organiser announcements. Announcements are written in a rich-text editor and inserted with innerHTML. The team adds a report-only Trusted Types header and, over a week, sees reports from three places: the announcements panel, a toast message component and a third-party feedback widget.

They change the toast component to textContent, since it only ever shows plain text. They route announcements through a single app-html policy using a sanitiser, and allow only that policy name with the trusted-types directive. The widget vendor's documentation doesn't mention Trusted Types, so the team loads it on a separate help page instead of the booking flow. After another quiet week of reports, they switch to enforcement.

FAQ

Does Trusted Types replace input validation and output escaping?

No. It's a safety net for client-side code. Server-side escaping, validation and a good Content Security Policy are still needed.

Will it slow my site down?

The check itself is done by the browser at the moment of assignment. The main cost is whatever sanitiser your policy runs, which you'd want anyway when inserting untrusted HTML.

What happens in browsers that don't support it?

They ignore the directive and run your code as before. Policies created through a small feature check or a polyfill keep the same code working everywhere.

Is this worth it for a simple brochure site?

If the site has little client-side rendering of untrusted data, probably not a priority. It pays off most in web apps, dashboards and portals that render user or partner content.

If you'd like help finding the risky DOM writes in your web app before switching on enforcement, send us a note about your front end.

Sources

WhatsAppBook a call