HTML Reference Β· Embedded Content
The <iframe> element
Reference for the HTML <iframe> element: src, srcdoc, name, every sandbox token, allow, allowfullscreen, loading, referrerpolicy, sizing, security and accessibility.
The <iframe> element (inline frame) shows another web page inside the current one. The framed page gets its own browsing context: its own document, styles, scripts and history entries, completely separate from the page that embeds it. Maps, video players, payment widgets and code previews are usually iframes.
Point it at a URL with src, or write the framed page's HTML straight into srcdoc. Always give it a title that says what it contains.
<iframe src="https://example.com/map" title="Map of the venue" width="600" height="400"></iframe>
Try it
The links use target="viewer", which matches the iframe's name, so the pages open inside the frame instead of replacing the whole page.
Both frames contain the same HTML. An empty sandbox applies every restriction; allow-scripts lifts just one of them.
Attributes
| Attribute | Values | Description |
|---|---|---|
src |
URL | The page to show. Without src or srcdoc, the frame contains an empty about:blank page. |
srcdoc |
HTML | The full HTML of the framed page, written inside the attribute. Takes priority over src. Escape " as " and & as &. |
name |
Text | A name for the frame's browsing context, used as a target by links and forms, and by window.open(). Must not start with an underscore. |
title |
Text | A global attribute, but essential here: it is the frame's accessible name. |
sandbox |
Empty, or space-separated tokens (see below) | Applies extra restrictions to the framed content. Empty means everything is restricted; each token re-enables one ability. |
allow |
Permissions Policy list, such as fullscreen; camera 'none'; autoplay |
Controls which powerful features the framed page may use (camera, microphone, geolocation, fullscreen, autoplay, clipboard and more). |
allowfullscreen |
Boolean | Lets the framed page enter fullscreen. Equivalent to allow="fullscreen"; prefer allow in new code. |
loading |
eager (default), lazy |
lazy delays loading the frame until it is near the viewport. |
referrerpolicy |
no-referrer, origin, same-origin, strict-origin-when-cross-origin, β¦ |
How much referrer information to send when loading the frame. |
width |
Non-negative integer | The width in CSS pixels. Default: 300. |
height |
Non-negative integer | The height in CSS pixels. Default: 150. |
It also accepts the other global attributes and the onload event attribute. The old attributes frameborder, scrolling, marginwidth, marginheight, align and longdesc are obsolete; use CSS (border, overflow on the framed page) instead. allowpaymentrequest and allowusermedia were replaced by allow.
sandbox tokens
| Token | Lifts the restriction on⦠|
|---|---|
allow-scripts |
Running JavaScript. |
allow-same-origin |
Being treated as its real origin. Without it, the frame has a unique opaque origin: no cookies, storage or same-origin access. |
allow-forms |
Submitting forms. |
allow-modals |
Opening alert(), confirm(), prompt(), print() and modal dialogs triggered by the sandboxed page. |
allow-popups |
Opening new windows or tabs (window.open(), target="_blank"). |
allow-popups-to-escape-sandbox |
Letting those new windows open without inheriting the sandbox. |
allow-top-navigation |
Navigating the top-level page (for example with target="_top"). |
allow-top-navigation-by-user-activation |
Navigating the top-level page, but only right after a user gesture such as a click. |
allow-top-navigation-to-custom-protocols |
Opening links with non-HTTP schemes, such as mailto:, in the top-level page. |
allow-downloads |
Starting file downloads. |
allow-pointer-lock |
Using the Pointer Lock API. |
allow-orientation-lock |
Locking the screen orientation. |
allow-presentation |
Starting a presentation session (Presentation API). |
Never combine allow-scripts and allow-same-origin for content from your own origin. Together they let the framed page's script reach into its parent and remove its own sandbox attribute, making the sandbox pointless.
Usage notes
- Always add
title. Screen readers announce iframes by their title. "Map of the venue" tells the user whether to explore it; no title leaves them guessing. - Many sites refuse to be framed. A server can forbid framing with the
Content-Security-Policy: frame-ancestorsheader orX-Frame-Options. The iframe then shows an error page; there is nothing the embedding page can do about it. - Same-origin vs. cross-origin. For a page from your own origin, scripts can reach the frame's document through
iframe.contentDocument. Across origins, the two pages can only talk withpostMessage(). - Responsive frames. Set
width: 100%and anaspect-ratioin CSS (such asaspect-ratio: 16 / 9; height: auto) instead of fixed pixel sizes. - Performance and privacy. Each iframe loads a whole page, often with third-party scripts and cookies. Use
loading="lazy"for frames below the fold, and consider a click-to-load placeholder for heavy embeds. - Tightening third-party embeds. Add
sandboxwith just the tokens the embed needs, anallowlist for powerful features, andreferrerpolicyif the URL shouldn't leak.
Technical summary
| Content categories | Flow content, phrasing content, embedded content, interactive content, palpable content |
| Permitted content | Nothing (any text between the tags is ignored) |
| Tag omission | None; both the start and end tags are required |
| Permitted parents | Any element that accepts embedded content |
| Implicit ARIA role | No corresponding role |
| DOM interface | HTMLIFrameElement |
| Default display | inline (a replaced element, 300 Γ 150 pixels by default, with a 2px inset border) |
Browser support
Supported in every browser, including srcdoc, sandbox, allow and loading="lazy".
Related
<embed>β embedding non-HTML resources<object>β an embed with fallback content<a>β thetargetattribute that loads links into a named frame- Lesson: Iframes
- Lesson: Embedding Content
- Lesson: Link Targets
- Lesson: Accessibility