Iframe Cheatsheet

iframe_cheatsheet.md

Iframe Developer Cheatsheet

A complete reference for HTML <iframe> properties, attributes, methods, and events.

---

🧩 HTML Attributes

Attribute	Description
src	URL of the document to embed.
srcdoc	Inline HTML to render inside the iframe (overrides src).
name	Name of the browsing context (used for form targets or window.open).
width, height	Sets the display size of the iframe.
sandbox	Restricts iframe capabilities. Flags: allow-scripts, allow-same-origin, allow-forms, allow-popups, etc.
allow	Defines permissions policy (e.g., camera; microphone; geolocation).
referrerpolicy	Controls referrer info sent with requests (no-referrer, origin, etc.).
loading	Lazy load behavior (lazy or eager).
allowfullscreen	Enables fullscreen capability.
allowpaymentrequest	Enables Payment Request API in iframe.
credentialless	Creates an iframe without credentials (experimental).
csp	Inline Content-Security-Policy specific to the iframe.
title	Accessible title for screen readers.
frameborder, scrolling	Deprecated legacy attributes.

---

🧩 Inline Event Handlers and Input Forms

You can attach event handlers directly in the HTML tag, similar to other elements. These can trigger scripts when certain events (like load, error, etc.) fire.

Example: Inline Event Handler

<iframe src="//example.com" onload="this.contentWindow.postMessage('hi', '*')"></iframe>

Example: Using srcdoc

You can provide inline HTML content using srcdoc instead of src:

<iframe srcdoc="<p>Hello from inline HTML!</p><script>window.parent.postMessage('Hello parent', '*')<\/script>"></iframe>

Example: With Multiple Attributes

<iframe
  src="https://example.com/page"
  name="myFrame"
  width="600"
  height="400"
  allow="camera; microphone"
  sandbox="allow-scripts allow-same-origin"
  onload="console.log('Iframe loaded:', this.src)"
></iframe>

You can add event handlers like onload, onerror, or even custom inline logic that interacts with the iframe's content via contentWindow, depending on origin and sandbox rules.

---

🧠 DOM Properties

On <iframe> element

Property	Description
iframe.contentWindow	The iframe's window object. (Same-origin only)
iframe.contentDocument	The iframe's document object. (Same-origin only)
iframe.src, iframe.srcdoc	Same as HTML attributes.
iframe.name	Name of the iframe.
iframe.sandbox	Returns or sets sandbox restrictions.
iframe.allow	Permissions policy string.
iframe.referrerPolicy	Referrer policy string.
iframe.loading	Lazy loading mode.
iframe.allowFullscreen	Boolean enabling fullscreen.
iframe.allowPaymentRequest	Boolean for Payment Request API.
iframe.width, iframe.height	Element dimensions.

From contentWindow

Property / Method	Description
win.postMessage(message, targetOrigin, [transfer])	Cross-document messaging.
win.document	DOM inside the iframe. (Same-origin only)
win.location	URL of the iframe’s page (read/write if same-origin).
win.history, win.navigator	Iframe’s browser context.
win.parent	Parent window.
win.top	Topmost window in hierarchy.
win.frameElement	Reference to the iframe element.
win.addEventListener('message', handler)	Handle postMessage events.

---

⚙️ Methods

Method	Description
iframe.getSVGDocument()	Returns SVG document if iframe displays an SVG.
iframe.setAttribute(name, value)	Sets an attribute.
iframe.removeAttribute(name)	Removes an attribute.
iframe.focus()	Focuses the iframe.
iframe.blur()	Removes focus from iframe.
iframe.contentWindow.postMessage()	Send cross-origin messages.

---

🔔 Events

Event	Triggered When
load	Iframe content is fully loaded.
error	Failed to load content.
message (on window)	When postMessage is received.
beforeunload, unload	Inside iframe: document is unloading.
DOMContentLoaded	Inside iframe: DOM is ready.

Example

const iframe = document.querySelector('iframe');

iframe.addEventListener('load', () => {
  console.log('Iframe loaded:', iframe.contentWindow.location.href);
});

window.addEventListener('message', (event) => {
  console.log('Received message:', event.data, 'from', event.origin);
});

---

🔐 Security and Same-Origin Policy

Concept	Description
Same-Origin Policy	You can only access contentWindow.document if both documents share the same origin.
Cross-Origin Access	You cannot read or modify iframe DOM, but you can use postMessage.
Sandboxing	Add restrictions with sandbox attribute; remove individual restrictions using tokens.
postMessage	Securely communicate between parent and iframe across origins.

Example: Cross-Origin Messaging

// parent window
iframe.contentWindow.postMessage({ action: 'ping' }, 'https://trusted.com');

// inside iframe
window.addEventListener('message', (event) => {
  if (event.origin === 'https://parent.com') {
    console.log('Received:', event.data);
  }
});

---

🧩 Special Objects & References

Object	Description
window.frames	Collection of all iframes in a document.
window.parent	Parent window (if inside an iframe).
window.top	Topmost window in hierarchy.
window.frameElement	Reference to the iframe element that contains the document.

Example

if (window.top !== window.self) {
  console.log('Running inside an iframe');
  console.log('My frame element:', window.frameElement);
}

---

🧭 Experimental / Less Common APIs

API	Description
iframe.loading = 'lazy'	Defers loading until near viewport.
iframe.csp	Inline CSP policy specific to iframe.
iframe.credentialless	Iframe runs without cookies or credentials.
window.crossOriginIsolated	True if context is isolated for SharedArrayBuffer.

---

✅ Summary

• Use contentWindow for interaction (same-origin only).
• Use postMessage for secure cross-origin communication.
• Always configure sandbox and allow attributes for security.
• Use lazy loading and referrer policies for performance and privacy.
• Inline attributes like src, srcdoc, and event handlers (onload, onerror) can embed or interact with content safely when used correctly.

---