XSS & safe DOM updates

What XSS means

XSS is short for cross-site scripting. It is a security bug in a web page. It happens when text from outside your code gets treated as code by the browser.

Text that comes from outside your code is called untrusted data. You don't control what it says. Some examples:

• what someone typed in a search box or a form
• a comment or a profile field that another user wrote
• data from an API
• the part of the URL after #, called the hash
• a draft saved in storage, or a message from another window

This text should stay plain data. But some browser features read a string as HTML, as a link, or as JavaScript. If untrusted data reaches one of those features, the browser may:

• build new elements on the page
• run event handlers, such as onclick
• follow a javascript: link, which runs code
• run the string as JavaScript

Only test pages you own or have permission to test. Every demo in this lesson is harmless. It sets a flag inside a sandbox (a locked-off mini page) or prints some text. Nothing in it does real damage.

Why does it matter? If someone else's script runs in a user's page, it can:

• read any data the page can read
• do things as that user, such as send a form
• change what the page shows, so the user trusts something false
• steal login tokens that JavaScript can reach

So the rule for this whole module is: never trust input. Check it, escape it, clean it, and limit what the browser is allowed to run.

To find XSS, follow the data from where it comes in to where it ends up. Two words help:

• A source is a place where untrusted data comes into your code.
• A sink is a browser feature that reads a string as HTML, as a link, or as JavaScript.

Common sources are values in the URL (after ? or #), form fields, API responses, postMessage data (messages from other windows), localStorage, pasted text, and anything another user saved.

1// Sources: places untrusted data can enter your code.2const fromUrl = new URLSearchParams(location.search).get("q");3const fromHash = location.hash.slice(1);4const fromStorage = localStorage.getItem("draft-comment");5const fromMessage = event.data; // only after checking event.origin6const fromApi = await response.json();7 8// Dangerous sinks: strings become code or markup.9output.innerHTML = fromUrl;10card.outerHTML = fromApi.html;11panel.insertAdjacentHTML("beforeend", fromStorage);12document.write(fromHash);13link.href = fromUrl; // dangerous when the scheme is javascript:14setTimeout(fromMessage, 0); // string form evaluates code

Lines 2 to 6 are sources. Lines 9 to 14 are dangerous sinks. Each sink line sends a source straight in, with no check. This block only lists names, so it doesn't run.

XSS has three names, based on the path the data takes:

• Reflected XSS: the server takes a value from the request and sends it straight back in the page.
• Stored XSS: the value is saved first, for example in a database. Later it is shown to this user or to another one.
• DOM-based XSS: JavaScript in the browser reads a source, such as the URL hash, and puts it into a sink.

Saving text in a database does not make it safe. Escape it or clean it each time you show it, based on where it goes.

1const request = { search: "tea" };2console.log("reflected:", request.search);3 4const savedComment = { body: "Nice tea" };5console.log("stored:", savedComment.body);6 7const fakeLocation = { hash: "#tea" };8const results = { textContent: fakeLocation.hash.slice(1) };9console.log("DOM-based:", results.textContent);

Each group of lines models one path:

• Lines 1 and 2: a request value that is sent back (reflected).
• Lines 4 and 5: a saved comment loaded for a reader (stored).
• Lines 7 to 9: browser code reads a hash and puts it in a text-only result (DOM-based).

The output is reflected: tea, stored: Nice tea, then DOM-based: tea. These are plain objects that only model the paths. In a real app, a server handles the request and the saving.

Now compare two sinks. textContent is a safe sink: it shows a string as text. innerHTML is a dangerous sink: it reads a string as HTML and builds real elements.

Try it yourself. The playground below sends the same harmless string to different sinks. It runs inside a sandboxed iframe, a mini page that can't touch this lesson page.

1const payload = '<button onclick="window.xssRan = true">Run handler</button>';2const host = document.querySelector("#comment-output");3 4window.xssRan = false;5host.innerHTML = payload;6host.querySelector("button")?.click();7console.log("innerHTML handler ran:", window.xssRan === true);8 9window.xssRan = false;10host.textContent = payload;11host.querySelector("button")?.click();12console.log("textContent handler ran:", window.xssRan === true);13 14window.scriptRan = false;15host.innerHTML = "<script>window.scriptRan = true;<\/script>";16console.log("script inserted with innerHTML ran:", window.scriptRan === true);

Modern browsers, including Chrome, don't run a <script> element added with innerHTML. That does not make innerHTML safe. These can still cause harm:

• event handler attributes, such as onclick or onerror
• links with a dangerous scheme, such as javascript:
• unusual SVG and MathML markup
• markup that changes how the page looks or acts

The demo uses an onclick handler and calls .click() itself, so the result is the same every time. An <img onerror> handler would run later, at a moment you can't predict, which is harder to test.

A context is the kind of place your text ends up. It can be HTML text, an HTML attribute, a URL, JavaScript, or CSS. Each context has its own special characters.

Sometimes you must build an HTML string from plain text. Then you escape the text. That means you swap each special character for a short code called an entity. For example, < becomes <. The browser shows an entity as the plain character, so it can't start a tag.

For HTML text and for quoted HTML attributes, escape five characters: &, <, >, the double quote ", and the single quote '.

Escape & too, because every entity starts with it. If you swap characters with separate replace calls, swap & first. Otherwise the & inside a new < gets swapped again. The helper below avoids that problem: one replace call handles all five characters in a single pass.

1const htmlEscapes = {Run2  "&": "&amp;",3  "<": "&lt;",4  ">": "&gt;",5  '"': "&quot;",6  "'": "&#39;",7};8 9function escapeHtml(value) {10  return String(value).replace(/[&<>"']/g, (character) => htmlEscapes[character]);11}12 13const comment = 'Tom & <img src=x onerror="console.log(\'XSS ran\')">';14console.log(escapeHtml(comment));

1const htmlEscapes = {2  "&": "&amp;",3  "<": "&lt;",4  ">": "&gt;",5  '"': "&quot;",6  "'": "&#39;",7};8 9function escapeHtml(value) {10  return String(value).replace(/[&<>"']/g, (character) => htmlEscapes[character]);11}12 13const comment = 'Tom & <img src=x onerror="console.log(\'XSS ran\')">';14console.log(escapeHtml(comment));

Lines 1 to 7 list the five characters and their entities. Line 10 uses a regular expression to find each of those characters, and swaps it for its entity. Line 14 prints Tom & <img src=x onerror="console.log('XSS ran')">.

Escaping only works for one context. HTML text, quoted attributes, URLs, JavaScript strings, and CSS values all have different rules. One helper used everywhere does not make a page safe. It is better to use DOM features that never build a string at all:

• textContent for text
• setAttribute for attributes you know are safe
• classList for classes
• addEventListener for behavior

1const user = '<img src=x onerror="console.log(1)">';2 3// HTML body context: encode markup characters.4message.innerHTML = escapeHtml(user);5 6// Attribute context: quote the attribute and escape quotes.7card.setAttribute("aria-label", user);8 9// URL context: parse and allow only expected schemes.10link.href = safeUrlAttribute(userUrl);11 12// JavaScript and CSS contexts: do not build code or style text with user data.13button.addEventListener("click", () => save(user));

Read it one context at a time:

• Line 4 puts text into HTML, so it escapes the markup characters first.
• Line 7 sets an attribute with setAttribute, which stores the value as text. No quote can break out.
• Line 10 sets a link, so it parses the URL and allows only the schemes it expects.
• Line 13 needs behavior. It never builds code or styles from user text; it passes the value to a function.

URLs need parsing, not a check of how the string starts. A URL's scheme is the part before the colon, such as https: or mailto:. Parse the value with the URL object and a known base URL. Then allow only the schemes your feature needs. In this lesson, the allowed list is http:, https:, and mailto:. Reject everything else: javascript:, data:, unknown schemes, and values that fail to parse.

1function safeUrlAttribute(raw, base = "https://completefrontend.com/javascript/xss") {2  try {3    const url = new URL(raw, base);4    if (["http:", "https:", "mailto:"].includes(url.protocol)) return url.href;5  } catch {6    return "about:blank";7  }8  return "about:blank";9}10 11console.log(safeUrlAttribute("/profile?user=ada"));12console.log(safeUrlAttribute("mailto:help@example.com"));13console.log(safeUrlAttribute("javascript:console.log('XSS ran')"));

Line 3 parses the value. Line 4 returns the full URL only if its scheme is on the list. Lines 11 to 13 print https://completefrontend.com/profile?user=ada, mailto:help@example.com, then about:blank. about:blank is an empty page that does nothing, so it is a safe fallback.

HTML escaping also works inside a quoted HTML attribute. It only fits attributes that hold plain text, such as a label. Line 7 below escapes the label while it builds the button string. When you can, use setAttribute for a text attribute instead. Remember: escaping does not make a URL safe, and setAttribute doesn't check a URL either.

1function escapeHtmlAttribute(value) {2  const entities = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };3  return String(value).replace(/[&<>"']/g, (character) => entities[character]);4}5 6const label = 'Asha says "tea" & coffee';7console.log('<button aria-label="' + escapeHtmlAttribute(label) + '">Open</button>');

The output is <button aria-label="Asha says &quot;tea&quot; &amp; coffee">Open</button>. The quotes and the & inside the label are now entities, so they can't end the quoted attribute. Don't reuse this output in a URL, in JavaScript, or in CSS.

1function safeProfileHref(raw, base = "https://completefrontend.com/") {2  const url = new URL(raw, base);3  return ["http:", "https:"].includes(url.protocol) ? url.href : "about:blank";4}5 6console.log(safeProfileHref("/members/asha"));7console.log(safeProfileHref("javascript:"));

The first call prints https://completefrontend.com/members/asha. The second prints about:blank, because javascript: is not on the list. The list checks the scheme only, not the site. If links must stay on your own site, also compare url.origin (the scheme plus the site name) with your own origin.

Sometimes a feature really does allow markup. Examples are rich-text comments, formatted help text, link previews, or a profile bio with bold text and links. Escaping would show the tags as text instead of formatting them. In that case you need a sanitizer. A sanitizer:

• parses the HTML into elements, the way the browser does
• keeps only the tags on an allowlist, a short list of things that are allowed
• removes unsafe attributes, such as onclick
• checks the scheme of every link
• turns the clean result back into HTML text

1import DOMPurify from "dompurify";2 3const clean = DOMPurify.sanitize(dirtyHtml, {4  ALLOWED_TAGS: ["b", "i", "a", "p", "ul", "li"],5  ALLOWED_ATTR: ["href"],6});7 8preview.innerHTML = clean;

DOMPurify is a well-known sanitizer library that its authors keep up to date. Lines 3 to 5 clean the HTML. They allow six tags and one attribute, href. DOMPurify still checks link schemes and removes dangerous ones. Line 8 inserts the clean result.

DOMPurify is not installed on this site, so this example can't run here. There are two ways to choose the allowed HTML: a ready-made profile, such as USE_PROFILES, or your own tag list, as here. Pick one; don't mix them without a reason.

1const policy = trustedTypes.createPolicy("comments", {2  createHTML(dirtyHtml) {3    return DOMPurify.sanitize(dirtyHtml, {4      USE_PROFILES: { html: true },5      RETURN_TRUSTED_TYPE: false,6    });7  },8});9 10preview.innerHTML = policy.createHTML(dirtyHtml);

Here DOMPurify runs inside createHTML, a policy method you'll meet in the Trusted Types section below. RETURN_TRUSTED_TYPE: false on line 5 tells DOMPurify to return a plain string. The policy then wraps that string as TrustedHTML itself. Use the sanitizer's result as it is. Don't change the string after it.

1const target = document.querySelector("#rich-output");2const dirty = "<b>Hello</b> <i>friend</i>";3 4if (typeof target.setHTML === "function") {5  target.setHTML(dirty);6  console.log("safe text:", target.textContent);7} else {8  console.log("setHTML unavailable: use DOMPurify or another sanitizer");9}

Line 4 checks that setHTML exists. Line 5 inserts the HTML safely, and line 6 prints the text that is now on the page. Line 8 runs in browsers that don't have setHTML.

Three warnings:

• setHTML() is safe. setHTMLUnsafe() is a different method that does not clean. Don't switch to it just to keep active content.
• After cleaning, don't turn the result into a string and insert it again with innerHTML. Use a safe insert method again.
• Don't clean HTML with a regex. HTML has attributes, entities, nested tags, and rules for fixing broken markup. A regex can't follow all of them. See when not to use a regex.

1const dirty = '<img src=x onerror="console.log(1)"><scr' + 'ipt>console.log(2)</scr' + 'ipt>';2const withoutScripts = dirty.replace(/<script.*?>.*?<\/script>/gi, "");3console.log(withoutScripts);

Line 2 removes the <script> tags. Line 3 prints <img src=x onerror="console.log(1)">. The image and its onerror handler are still there.

A real sanitizer works on parsed elements, not on text. Step through the decisions of a small teaching sanitizer:

1const allowedTags = new Set(["B", "I", "A"]);Run2const allowedSchemes = new Set(["http:", "https:", "mailto:"]);3const sample = 'Hello <b onclick="x()">bold</b> <a href="javascript:alert(1)">bad</a> <a href="https://example.com">ok</a>';4 5function sanitizeTeachingHtml(html) {6  const parsed = parseToNodes(html);7  const cleanNodes = parsed.flatMap(cleanNode);8  return cleanNodes.join("");9}10 11console.log(sanitizeTeachingHtml(sample));12 13function parseToNodes(_html) {14  return [15    { type: "text", text: "Hello " },16    { type: "element", tag: "B", children: [{ type: "text", text: "bold" }] },17    { type: "text", text: " " },18    { type: "element", tag: "A", href: "javascript:alert(1)", children: [{ type: "text", text: "bad" }] },19    { type: "text", text: " " },20    { type: "element", tag: "A", href: "https://example.com", children: [{ type: "text", text: "ok" }] },21  ];22}23 24function cleanNode(node) {25  if (node.type === "text") return [node.text];26  if (!allowedTags.has(node.tag)) return node.children.flatMap(cleanNode);27  const href = node.tag === "A" && allowedUrl(node.href) ? ` href="${node.href}" rel="noopener noreferrer"` : "";28  const body = node.children.flatMap(cleanNode).join("");29  return [`<${node.tag.toLowerCase()}${href}>${body}</${node.tag.toLowerCase()}>`];30}31 32function allowedUrl(value) {33  try {34    return allowedSchemes.has(new URL(value, "https://example.com/").protocol);35  } catch {36    return false;37  }38}

Here is the full teaching sanitizer, which runs in the browser:

1function isSafeUrl(value) {2  try {3    const url = new URL(value, "https://example.com/");4    return ["http:", "https:", "mailto:"].includes(url.protocol);5  } catch {6    return false;7  }8}9 10function sanitizeTeachingHtml(dirtyHtml) {11  const allowedTags = new Set(["B", "I", "A"]);12  const dropWithChildren = new Set(["SCRIPT", "STYLE", "IFRAME", "OBJECT", "EMBED", "SVG", "MATH"]);13  const parser = new DOMParser();14  const parsed = parser.parseFromString(dirtyHtml, "text/html");15  const output = document.createElement("template");16 17  function cleanInto(node, parent) {18    if (node.nodeType === Node.TEXT_NODE) {19      parent.append(document.createTextNode(node.textContent ?? ""));20      return;21    }22    if (node.nodeType !== Node.ELEMENT_NODE) return;23    if (dropWithChildren.has(node.tagName)) return;24    if (!allowedTags.has(node.tagName)) {25      node.childNodes.forEach((child) => cleanInto(child, parent));26      return;27    }28 29    const clean = document.createElement(node.tagName.toLowerCase());30    if (node.tagName === "A") {31      const href = node.getAttribute("href")?.trim() ?? "";32      if (isSafeUrl(href)) {33        clean.setAttribute("href", href);34        clean.setAttribute("rel", "noopener noreferrer");35      }36    }37    node.childNodes.forEach((child) => cleanInto(child, clean));38    parent.append(clean);39  }40 41  parsed.body.childNodes.forEach((child) => cleanInto(child, output.content));42  const wrapper = document.createElement("div");43  wrapper.append(output.content.cloneNode(true));44  return wrapper.innerHTML;45}46 47const dirty = 'Hello <b onclick="x()">bold</b> <i>friend</i> ' +48  '<a href="javascript:alert(1)" onclick="x()">bad</a> ' +49  '<a href="https://example.com">ok</a>' +50  '<' + 'script>console.log("x")</' + 'script><img src=x onerror="x()">';51console.log(sanitizeTeachingHtml(dirty));

The main lines, in order:

1. Lines 11 and 12 list the allowed tags, and the dangerous tags to drop with everything inside them.
2. Lines 13 and 14 parse the HTML with DOMParser, the browser's own HTML reader. Nothing on the page runs it.
3. Line 18 copies text as plain text.
4. Line 23 drops dangerous tags, such as <script>, with their content.
5. Line 24 handles any other tag that is not on the list: it keeps only the text inside.
6. Line 29 makes a fresh, empty copy of an allowed tag, so no attributes come along.
7. Line 32 keeps a link's href only if its scheme is safe.
8. Line 44 returns the clean HTML as a string.

Line 51 prints Hello <b>bold</b> <i>friend</i> <a>bad</a> <a href="https://example.com" rel="noopener noreferrer">ok</a>. The script and the image are gone.

Each row below is one way to handle HTML from users. Read across to see what it looks like and when to use it.

Trusted Types is a browser guard against DOM-based XSS. You turn it on with a CSP rule, which the next section explains: require-trusted-types-for 'script'. Then dangerous sinks such as innerHTML refuse plain strings. They only accept a TrustedHTML object.

A TrustedHTML object comes from a policy. A policy is a small named object that you create. Its job is to check or clean the HTML before it reaches a sink.

1if (!window.trustedTypes) {2  throw new Error("Trusted Types are not available in this browser");3}4 5const target = document.querySelector("#trusted-target");6try {7  target.innerHTML = "<b>plain string</b>";8  throw new Error("Trusted Types enforcement is not active");9} catch (error) {10  console.log(error.name);11  throw error;12}

Line 7 sets innerHTML to a plain string. With Trusted Types on, the browser throws a TypeError. Line 10 prints its name, and line 11 throws it again. If the browser doesn't enforce Trusted Types, line 8 throws an error that says so.

1if (window.trustedTypes) {2  const policy = trustedTypes.createPolicy("lesson", {3    createHTML(value) {4      return value;5    },6  });7 8  const target = document.querySelector("#trusted-target");9  target.innerHTML = policy.createHTML("<b>Trusted Types policy output</b>");10  console.log(target.textContent);11} else {12  console.log("Trusted Types unavailable: keep escaping and sanitizing");13}

Line 2 creates a policy named lesson. Its createHTML method, on line 3, returns the value it gets. Line 9 passes the policy's TrustedHTML to innerHTML, and the browser accepts it. Line 10 prints Trusted Types policy output.

This policy returns its input unchanged, only to show how the parts fit. It is not safe for untrusted data. A real policy must clean the HTML, as in the DOMPurify example above. Trusted Types does not clean anything by itself.

More browsers support Trusted Types than the Sanitizer API. But older browsers and browsers built into apps may not. It only works when the browser follows the CSP rule.

Content Security Policy, or CSP, is a list of rules that tells the browser what a page may load and run. The server sends it with the page. The best way is an HTTP response header: a line of extra information that arrives with the page. A meta tag in the HTML can set some rules too. But it can't set frame-ancestors, and it can't turn on report-only mode.

CSP is a backup layer. It limits the damage when a bug slips through. It does not replace escaping, URL checks, sanitizing, or careful code review.

1Content-Security-Policy:2  default-src 'self';3  script-src 'nonce-{fresh-random-value-per-response}' 'strict-dynamic';4  object-src 'none';5  base-uri 'self';6  frame-ancestors 'none';7  require-trusted-types-for 'script';8  trusted-types lesson dompurify;

What each line does:

• Line 2, default-src, is the fallback rule for anything the other lines don't name.
• Line 3, script-src, allows only scripts that carry the right nonce. A nonce is a random value. The server makes a new one for each response and puts it on its own script tags. Never hard-code a nonce or reuse one. 'strict-dynamic' lets those trusted scripts load more scripts.
• Line 4, object-src 'none', blocks old plugin content.
• Line 5, base-uri 'self', stops an injected <base> tag from changing where relative links point.
• Line 6, frame-ancestors, controls which sites may show your page inside a frame.
• Line 7, require-trusted-types-for 'script', turns on the Trusted Types checks.
• Line 8, trusted-types, lists the policy names the page may create.

1Content-Security-Policy-Report-Only:2  default-src 'self';3  script-src 'self';

The Content-Security-Policy-Report-Only header reports rule breaks but does not block them. To receive the reports, set up a reporting endpoint: an address on your server that collects them. Watch real traffic and fix the gaps. Then send the enforcing Content-Security-Policy header.

Real-world patterns

Many features show data that someone else can change. Some examples are comment widgets, search results, rich-text editors, link previews, support inboxes, notification templates, and dashboards. The steps are the same every time:

1. Find the source of the data.
2. Pick the safest sink.
3. Check every URL.
4. Sanitize only when markup is required.
5. Add Trusted Types and CSP, so mistakes get caught.

1// React escapes text in JSX by default.2function Comment({ author, body }) {3  return <article><h3>{author}</h3><p>{body}</p></article>;4}5 6// Escape hatches put you back in charge of sanitizing.7function RichComment({ sanitizedHtml }) {8  return <article dangerouslySetInnerHTML={{ __html: sanitizedHtml }} />;9}10 11// Vue's {{ message }} escapes. v-html renders HTML and needs sanitized input.

Line 3 puts author and body into JSX as text, so React escapes them. Line 8 uses dangerouslySetInnerHTML, which inserts HTML with no escaping. Its HTML must be sanitized first. Line 11 says the same for Vue.

1React text: <p>{comment}</p>2React raw HTML: <div dangerouslySetInnerHTML={{ __html: reviewedHtml }} />3 4Vue text: <p>{{ comment }}</p>5Vue raw HTML: <div v-html="reviewedHtml"></div>6 7Svelte text: <p>{comment}</p>8Svelte raw HTML: {@html reviewedHtml}

In React, Vue, and Svelte, ordinary text bindings escape markup for you. Each framework also has a raw HTML escape hatch: a feature that skips the escaping on purpose. Lines 2, 5, and 8 show them. An escape hatch needs sanitized HTML.

Frameworks also don't check link schemes for you. Code that touches the DOM directly, or builds HTML strings, needs the same source-to-sink check. When you build your own rendering code, review template literals, eval and dynamic code, postMessage origin checks, web storage, and the tiny reactive UI lesson.

Each card below is a short checklist for one kind of feature.

Common misconceptions

• "Scripts added with innerHTML don't run, so innerHTML is safe." Not true. Event handler attributes, dangerous links, and other active markup still work.
• "Escaping once makes data safe everywhere." Not true. Escaping works for one context only. HTML, URLs, JavaScript, and CSS each have their own rules.
• "Sanitizing means removing script tags." Not true. A sanitizer needs an allowlist for tags, attributes, and URL schemes. Removing tags with a regex is not enough.
• "Trusted Types cleans HTML for me." Not true. Trusted Types only refuses plain strings. Your policy must still clean the HTML or build it safely.
• "CSP fixes XSS." Not true. CSP limits what can run and reports rule breaks. It is a backup layer, not the main defense.
• "Frameworks stop all XSS." Not true. Their automatic escaping helps until you use an escape hatch, direct DOM access, an unchecked URL, or an HTML string.

Each row below is one defense. Read across to see what it does and when to use it.

Key takeaways

• XSS is a bug where data turns into code. Start every check by following untrusted data from its source to its sink.
• For plain text, use textContent, safe framework bindings, or elements you build yourself. Avoid HTML strings when you can.
• Escape for the exact context. Check URLs with new URL() and a list of allowed schemes.
• When users may send HTML, use a well-kept sanitizer with an allowlist. The teaching sanitizer only shows the decisions.
• Trusted Types makes dangerous sinks refuse plain strings, and CSP limits what can run. Both are backup layers, not a replacement for safe sinks.

One-line summary: keep untrusted data from running as code: pick safe sinks first, sanitize only when markup is required, and add browser rules as a backup.

Up next: CSRF, cookies, and tokens. This lesson stops other people's code from running in your page. The next one protects the requests a logged-in user sends.