References

Beginner-friendly references for web development, with live, editable examples.

The HTML srcdoc attribute

Attribute All modern browsers By David AdamsUpdated
In short

The HTML srcdoc attribute holds the HTML that an <iframe> displays, as in srcdoc="<p>Hello</p>". Double quotes and ampersands inside the value must be escaped. The frame's document gets the address about:srcdoc, and srcdoc wins when src is set too.

Overview

The HTML srcdoc attribute gives an <iframe> its content as a string of HTML. The browser builds a whole document from that string, so a frame can show a preview, a widget or an email body without a separate file or URL.

A srcdoc value needs only body content, since the doctype and the html, head and body tags are optional. A normal page without a doctype falls into quirks mode, the old rendering mode, but srcdoc documents are exempt. A value of <p>Hi</p> produces a complete page.

A srcdoc document always has the address about:srcdoc, the same name Chrome's console uses for the frame. Relative links inside it resolve against the parent page's base URL, not against about:srcdoc. It also runs under the parent page's Content Security Policy.

Without a sandbox attribute, a srcdoc frame shares its parent's origin, which gives its scripts complete access to the parent page. A bare sandbox attribute blocks those scripts. With sandbox="allow-scripts", they run but get a SecurityError when they reach for the parent.

Syntax

<iframe title="Order preview" sandbox
  srcdoc="<p>Order <b>#1024</b> ships &quot;today&quot;.</p>"></iframe>

Values

Value
A string of HTML.

Example

Live example 
<label for="code">HTML to preview (scripts won't run)</label><br>
<textarea id="code" rows="3" cols="38"><h2>Hello</h2>
<p>This came from srcdoc.</p></textarea><br>
<button id="show">Preview</button>
<iframe id="frame" title="HTML preview" sandbox height="110" srcdoc="<p>Press Preview to load the HTML.</p>"></iframe>
<script>
document.getElementById('show').addEventListener('click', function () {
  document.getElementById('frame').srcdoc = document.getElementById('code').value;
});
</script>

Best practices

  • Add sandbox to every srcdoc frame that shows HTML you didn't write, and leave out allow-same-origin. Escaping keeps the markup inside the attribute but doesn't disarm it, since the browser decodes the attribute before building the frame.
  • Set markup from JavaScript through the iframe.srcdoc property. The property takes raw HTML, so you skip the quote and ampersand escaping that the attribute needs.
  • When you write the attribute by hand or on the server, turn each & into &amp; first and each " into &quot; second. Done in that order, each quote ends up as &quot;, not &amp;quot;.
  • Inside the frame, link to about:srcdoc#end rather than #end when a link should jump within the framed page, since #end resolves against the parent page's base URL.

Accessibility

Label every srcdoc frame with a title that describes what it holds. People using assistive technology can use the title to identify an iframe, so a title such as "Order preview" helps more than "Frame" or "Preview 2".

Frequently asked questions

What is about:srcdoc?
The URL about:srcdoc is the address of the document inside an iframe built with the srcdoc attribute. It names a document inside a page, not a website, so it can't be opened on its own.
What is the difference between srcdoc and src on an iframe?
The src attribute loads a page from a URL, while srcdoc carries the HTML itself. When an iframe has both, the srcdoc content is shown, and src only matters to browsers that don't support srcdoc.
How do I escape quotes inside srcdoc?
Inside srcdoc, write each double quote as &quot; and each ampersand as &amp;. An ampersand that the framed HTML itself escapes as &amp; therefore becomes &amp;amp; in the attribute.
Is srcdoc safe for HTML that users submit?
No, srcdoc alone isn't safe for user HTML, because an unsandboxed srcdoc frame shares your page's origin. Add sandbox without allow-same-origin, and escape every ampersand and double quote so the HTML can't break out of the attribute, or set the srcdoc property from script.
Why does Chrome block scripts in about:srcdoc?
Chrome blocks scripts in a srcdoc frame whose sandbox attribute leaves out allow-scripts. Its console then logs Blocked script execution in 'about:srcdoc', and the parent page's script-src policy can block the frame's scripts too.
Why does an anchor link inside a srcdoc iframe load the parent page?
A srcdoc document resolves relative links against its parent page's base URL. A link to #end therefore points at the parent page, while a link to about:srcdoc#end scrolls within the frame.
Can I change srcdoc with JavaScript?
Yes, assigning a new string to the srcdoc property reloads the iframe with that HTML. Under a Content Security Policy that enforces Trusted Types without a default policy, assign a TrustedHTML object instead.
src srclang