How to Use the iframe Element

The HTML iframe element displays another HTML document inside the current page. It is useful for a map, video, payment screen, or preview that needs to remain an independent document.

The answer first

Minimal example

<iframe
  src="https://example.com/help.html"
  title="How to use the service"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin">
</iframe>

src is the URL of the document to embed. The title helps both sighted readers and people using assistive technology understand the embedded area. Consider loading="lazy" when delaying the load will not harm the experience.

Display another document in the page

With srcdoc, the embedded HTML is provided in the attribute instead of at a URL. Because it is written inside an HTML attribute, inner < and > characters are escaped as < and >. Do not put untrusted user strings directly into HTML that you embed.

src and srcdoc

Declaration	Meaning	Useful for
src	Loads a document from a URL	External services, separate pages, published previews
srcdoc	Creates the document from the attribute value	Small fixed examples or generated previews
Both	srcdoc takes priority	Providing a URL fallback for older environments

Use src when the embedded document is large or should be maintained as its own URL. With srcdoc, remember that quotation marks and ampersands need careful escaping inside the attribute.

Use sandbox for additional restrictions

An empty sandbox attribute applies additional restrictions to the embedded document. Forms, scripts, popups, and other capabilities remain restricted unless the required tokens are added.

<iframe
  src="https://example.com/user-content.html"
  title="Post preview"
  sandbox="allow-scripts"
></iframe>

Use the smallest set of tokens that works. In particular, giving same-origin content both allow-scripts and allow-same-origin can let that content remove the sandbox in some situations. Do not assume that the combination is safe. Hostile HTML should also be served from a separate origin instead of relying on sandbox alone.

iframe versus a link

Goal	Use	How to think about it
Move to another place	a	The user chooses a link and navigates
Show another document in the current view	iframe	The parent page and child document are visible together
Separate information in the same document	Headings, section, and similar elements	Avoid creating an unnecessary document boundary

The iframe content is not merely a normal part of the parent document. It is loaded as another document. When the origins differ, the parent cannot freely read the child DOM. If the two documents need to communicate, use postMessage and check the receiving origin.

Accessibility and sizing

• Add a concise title that describes the embedded content.
• Do not put essential information only inside an iframe; provide another path when people need it.
• Avoid a fixed width that breaks on narrow screens, and check the height and scrolling behavior.
• Check that the embedded service supports keyboard interaction, headings, and sensible focus movement.

Common mistakes

• Leaving out title, so the purpose of the embedded area is unclear.
• Embedding outside content without considering sandbox or delegated permissions.
• Assuming that sandbox makes every attack harmless.
• Assuming that the parent can directly read the DOM of a cross-origin iframe.
• Using an iframe for ordinary content that could stay in the same document.

Read the Atlas reference

For the content navigable, src and srcdoc processing, initial about:blank, sandboxing, Permissions Policy, referrer behavior, lazy loading, same-origin boundaries, accessibility mappings, and browser evidence, see the iframe element page in Yugien Atlas.