Element: outerHTML property

Value

Getting the property returns a string containing an HTML serialization of the element and its descendants.

Setting the property accepts either a TrustedHTML object or a string. The input is parsed as HTML and replaces the element and all its descendants with the result. When set to the null value, that null value is converted to the empty string (""), so element.outerHTML = null is equivalent to element.outerHTML = "".

Exceptions

NoModificationAllowedError DOMException

Thrown if an attempt was made to set outerHTML on an element which is a direct child of a Document, such as Document.documentElement.

SyntaxError DOMException

Thrown if an attempt was made to set outerHTML using an XML input which is not well-formed.

TypeError

Thrown if the property is set to a string when Trusted Types are enforced by a CSP and no default policy is defined.

Description

outerHTML gets a serialization of the element, or sets HTML or XML that should be parsed to replace it within the element's parent.

If the element has no parent node, setting its outerHTML property will not change it or its descendants. For example:

const div = document.createElement("div");
div.outerHTML = '<div class="test">test</div>';
console.log(div.outerHTML); // output: "<div></div>"

Also, while the element will be replaced in the document, the variable whose outerHTML property was set will still hold a reference to the original element:

const p = document.querySelector("p");
console.log(p.nodeName); // shows: "P"
p.outerHTML = "<div>This div replaced a paragraph.</div>";
console.log(p.nodeName); // still "P";

Escaped attribute values

The returned value will escape some values in HTML attributes. Here we see that the & character is escaped:

const anchor = document.createElement("a");
anchor.href = "https://newreal1.mobosoft.fun?a=b&c=d";
console.log(anchor.outerHTML); // output: "<a href='https://newreal1.mobosoft.fun?a=b&amp;c=d'></a>"

Some browsers also serialize the < and > characters as < and > when they appear in attribute values (see Browser compatibility). This is to prevent a potential security vulnerability (mutation XSS) in which an attacker can craft input that bypasses a sanitization function, enabling a cross-site scripting (XSS) attack.

Shadow DOM considerations

The serialization of the DOM tree read from the property does not include shadow roots. If you want to get an HTML serialization of an element that includes shadow roots, you must instead use the Element.getHTML() method. Note that this gets the contents of the element.

Similarly, when setting element content using outerHTML, the HTML input is parsed into DOM elements that do not contain shadow roots. So for example <template> is parsed into as HTMLTemplateElement, whether or not the shadowrootmode attribute is specified. If you want to set an element's contents from an HTML input that includes declarative shadow roots, you must instead use Element.setHTMLUnsafe() or ShadowRoot.setHTMLUnsafe().

Security considerations

The outerHTML property is possible vector for Cross-site-scripting (XSS) attacks, as it can be used to inject potentially unsafe strings provided by a user into the DOM. While the property does prevent <script> elements from executing when they are injected, it is susceptible to many other ways that attackers can craft HTML to run malicious JavaScript. For example, the following example would execute the code in the error event handler, because the <img> src value is not a valid image URL:

const name = "<img src='x' onerror='alert(1)'>";
element.outerHTML = name; // shows the alert

You can mitigate these issues by always assigning TrustedHTML objects instead of strings, and enforcing trusted type using the require-trusted-types-for CSP directive. This ensures that the input is passed through a transformation function, which has the chance to sanitize the input to remove potentially dangerous markup before it is injected.

Examples

Getting the serialization of an element

Reading outerHTML causes the user agent to serialize the element.

Given the following HTML:

<div id="example">
  <p>Content</p>
  <p>Further Elaborated</p>
</div>

You can get and log the markup for the <div> as shown:

const myElement = document.querySelector("#example");
const contents = myElement.outerHTML;
console.log(contents);
// '<div id="example">\n  <p>Content</p>\n  <p>Further Elaborated</p>\n</div>'

Replacing the element

In this example we'll replace an element in the DOM by assigning HTML to the element's outerHTML property. To mitigate the risk of XSS, we'll first create a TrustedHTML object from the string containing the HTML, and then assign that object to outerHTML.

Trusted types are not yet supported on all browsers, so first we define the trusted types tinyfill. This acts as a transparent replacement for the trusted types JavaScript API:

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

Next we create a TrustedTypePolicy that defines a createHTML() for transforming an input string into TrustedHTML instances. Commonly implementations of createHTML() use a library such as DOMPurify to sanitize the input as shown below:

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

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

// The potentially malicious string
const untrustedString = "<p>I might be XSS</p><img src='x' onerror='alert(1)'>";

// Create a TrustedHTML instance using the policy
const trustedHTML = policy.createHTML(untrustedString);

// Inject the TrustedHTML (which contains a trusted string)
const element = document.querySelector("#container");
element.outerHTML = trustedHTML; // Replaces the element with id "container"

// Note that the  #container div is no longer part of the document tree,

Specifications

Browser compatibility

See also

• Serializing DOM trees into XML strings: XMLSerializer
• Parsing XML or HTML into DOM trees: DOMParser
• HTMLElement.outerText