Trusted Types — Polyfill

W3C polyfill · api_only · full · tinyfill · README.md

Table of contents

• Native vs polyfill — what the browser does natively vs api_only, full, and tinyfill
• Which browsers need the polyfill? — when you can omit the script vs when you still need a shim
• Polyfill variants — trade-offs and intent
  • 1. api_only (light)
  • 2. full
  • 3. Tinyfill (minimal shim)
• Load in the browser (ES5 builds) — CDN <script> tags for api_only and full
  • API only
  • Full (with inferred / inline CSP hint)
• Node.js / bundlers (npm) — npm install, CommonJS / ESM notes
• Pairing with application code — feature-detect pattern, DOMPurify + trusted output
  • Feature test (same as without polyfill)
  • DOMPurify + Trusted Types
• Building from source (optional) — clone upstream repo, npm run build
• Demo and tests — hosted demo and platform-test paths
• When you can skip the polyfill — native-only support matrix
• Related in this repo — README.md, playground/
• Links & resources — MDN, GitHub, npm, web.dev, CDN URLs

Native vs polyfill (what changes)

Which browsers need the polyfill?

Trusted Types is part of the interoperable web platform in current Chromium-, Firefox-, and Safari-based browsers (MDN documents the API under Baseline as broadly available in 2026—exact first versions change; use MDN browser compatibility or Can I use — Trusted Types for today’s matrix). For those engines, trustedTypes + CSP enforcement are native: you ship headers and policies; you do not need the polyfill for the API to exist or for the browser to enforce Trusted Types.

Polyfill variants

1. api_only (light)

• Defines the Trusted Types API so you can call createPolicy and use policy methods.

2. full

• Includes api_only behavior plus attempts type enforcement in the DOM based on a CSP policy inferred from the document (implementation: src/polyfill/full.js).
• In HTML you can pass a policy via data-csp on the script tag (see example below).

3. Tinyfill (minimal shim)

• Does not implement enforcement.
• Stubs trustedTypes.createPolicy so it returns your rules object; createHTML etc. return plain strings on non-supporting browsers, which legacy sinks accept.

Documented in the upstream README (Tinyfill section):

if (typeof trustedTypes === "undefined") {
  globalThis.trustedTypes = { createPolicy: (_name, rules) => rules };
}

Same idea, slightly more readable:

if (typeof trustedTypes === "undefined") {
  globalThis.trustedTypes = {
    createPolicy(_name, rules) {
      return rules;
    },
  };
}

Load in the browser (ES5 builds)

API only

<script src="https://w3c.github.io/webappsec-trusted-types/dist/es5/trustedtypes.api_only.build.js"></script>
<script>
  const p = trustedTypes.createPolicy("foo", {
    createHTML: (s) => /* sanitize */ s,
  });
  document.body.innerHTML = p.createHTML("<b>ok</b>");
  document.body.innerHTML = "<b>still allowed without native enforcement</b>";
</script>

Full (with inferred / inline CSP hint)

<script
  src="https://w3c.github.io/webappsec-trusted-types/dist/es5/trustedtypes.build.js"
  data-csp="trusted-types foo bar; require-trusted-types-for 'script'"
></script>
<script>
  trustedTypes.createPolicy("foo", { createHTML: (s) => s });
  // trustedTypes.createPolicy("unknown", { ... }); // throws if not in trusted-types list
  // document.body.innerHTML = "foo"; // intended to throw under polyfill enforcement
</script>

Node.js / bundlers (npm)

npm install trusted-types

CommonJS (shape per upstream README — Node.js):

const tt = require("trusted-types");
// or: import { trustedTypes } from "trusted-types"
tt.createPolicy("myPolicy", {
  createHTML: (input) => sanitize(input),
});

ES modules — check your package version’s exports field; many setups re-export trustedTypes on globalThis after a side-effect import instead of a named export.

Pairing with application code

Feature test (same as without polyfill)

if (globalThis.trustedTypes?.createPolicy) {
  const policy = trustedTypes.createPolicy("app", {
    createHTML: (s) => DOMPurify.sanitize(s),
  });
  el.innerHTML = policy.createHTML(userHtml);
}

DOMPurify + Trusted Types

DOMPurify can return a trusted type for direct sink assignment (native + polyfill API where applicable):

import DOMPurify from "dompurify";

el.innerHTML = DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true });

Building from source (optional)

git clone https://github.com/w3c/trusted-types.git
cd trusted-types
npm install
npm run build

Demo and tests

• Demo: w3c.github.io/trusted-types/demo
• Platform tests: tests/platform-tests in the upstream repo

When you can skip the polyfill

If you still support older Chromium / WebKit / Firefox without TT, keep api_only or tinyfill until those versions fall out of scope.

Related in this repo

• README.md — full patterns and CSP walkthrough; tinyfill is covered in H. Tiny polyfill.
• playground/ — DOM XSS vs Trusted Types / setHTML() demos (node playground/serve.mjs); see playground/README.md (not hosted on the static site).

Links & resources