a-iframe Custom Element

A lightweight Web Component that wraps a standard <iframe> to provide automatic height resizing and inline content injection.

It uses a ResizeObserver to monitor the inner document's height and automatically adjusts its own height to fit the content. It also handles injecting raw HTML directly into the iframe via slots.

Features

• Auto-Resizing: Automatically adjusts height based on same-origin content size.

• Attribute Proxying: Passes standard iframe attributes down to the internal <iframe>.

• Inline HTML Injection: Populate the iframe using inner DOM nodes.

• Safe HTML Parsing: Inject HTML via a <textarea> to prevent the parent window from executing scripts before they are sandboxed.

Demo: https://holmesbryant.github.io/a-iframe/

Installation

Import the module into your application:

<script
    type="module"
    src="path/to/a-iframe.min.js">
  </script>

Usage

Standard URL (src)

Works exactly like a normal iframe, but automatically adjusts its height.

Note: Auto-resizing requires the source to be Same-Origin).

<a-iframe src="local-page.html" title="My Local Page">
  </a-iframe>

Inline HTML Injection

You can write HTML directly inside the <a-iframe> tags. The component extracts this content, creates a Blob URL from it, and sets it as the internal iframe's src.

<a-iframe>
    <link rel="stylesheet" href="styles.css">

    <style>
      body { background: #f0f0f0; }
    </style>

    <h1>Hello from inside the iframe!</h1>
    <p>This content is automatically wrapped and rendered.</p>
  </a-iframe>

Secure Inline HTML (Using <textarea>)

If your inline HTML contains <script> tags, or if you simply want to prevent the browser from parsing your content before a-iframe can process it, place your inline HTML inside a <textarea>. The component will extract the value, hide the textarea, create a Blob URL from the content, and set the iframe's src to the URL.

<a-iframe >
    <!-- The textarea prevents the parent document from executing this script -->
    <textarea>
      <h1>Script Execution</h1>
      <script>
        console.log("I am running safely inside the iframe context.");
      </script>
    </textarea>
  </a-iframe>

Sandboxing

If you sandbox the iframe and your HTML is inline or is a local file, the sandbox attribute must include allow-same-origin. Otherwise the iframe will not resize.

Chromium based browsers will log an error, "Blocked script execution ..." but a-iframe will work correctly. The error is simply telling you that the sandbox is preventing script execution within the iframe.

<a-iframe
    src="file.html"
    sandbox="allow-same-origin">
  </a-iframe>

Important!

If the sandbox also includes allow-scripts, make sure you trust the content (or sanitize it before injecting it into a-iframe).

If both flags are present and the iframe content shares the parent's origin, the iframe's scripts can access window.parent.document. The script can then remove the sandbox attribute from its own iframe element or steal your site's cookies and local storage (XSS).

If the iframe src is cross-origin, this is not a concern. See the section on Cross Origin Resizing

Passing Standard Attributes

All standard security, loading, and feature-policy attributes are supported and proxied automatically.

<a-iframe
    src="widget.html"
    loading="lazy"
    allowfullscreen
    sandbox="allow-scripts allow-modals"
    referrerpolicy="no-referrer"
    name="custom-frame">
  </a-iframe>

Supported Attributes

The following standard iframe attributes are observed and actively proxied to the inner iframe element. Boolean attributes (like allowfullscreen) can be toggled dynamically.

• allow
• allowfullscreen
• credentialless
• csp
• importance
• loading
• name
• referrerpolicy
• sandbox
• src
• title

Cross Origin iframes

Due to strict browser security policies (CORS), the ResizeObserver cannot read the DOM size of cross-origin iframes. If src points to a different domain and a special script is not present in the source file, the auto-resize feature will fail gracefully and the iframe will behave normally.

In order for resizing to work on a cross-origin iframe, you must include this script in the head of the remote file.

<!-- remote-file.html -->
<head>
    ...
    <script type="module">
      new ResizeObserver((entries) => {
        const height = entries[0].target.offsetHeight;
        window.parent.postMessage({ type: 'resize', height }, '*');
      }).observe(document.documentElement);
    </script>
  </head>

In addition, if you sandbox the cross-origin iframe, your sandbox attribute must include allow-scripts.

<iframe src="..." sandbox="allow-scripts"></iframe>

License

GPL-3.0