i-HTML
i-HTML

The element is a drop-in tag that allows for dynamically importing HTML inline.

i-HTML fetches a requested HTML resource and replaces the element's inner contents with the parsed content of the response. It's similar to an <iframe> but adopts the HTML into the page.

Key functionalities and features of <i-html> include:

  • Basic Usage: The <i-html> tag is placed as an empty container, and when the src= attribute changes, it fetches the HTML and updates the content.

  • Targeting with Links: Like iframes, <i-html> respects the target= attribute on links, so a link with a target that matches the id of an <i-html> element will load the link's href into the element.

  • Targeting with Forms: Similarly, <i-html> respects target= attributes on forms, allowing forms to submit to an <i-html> element and load new content. Forms can also be wrapped in <i-html> elements to create "AJAX-style" forms. The formaction= attribute of buttons is also supported.

  • Content Selection: By default, <i-html> injects the <body> element's content but this can be customized with the target= attribute, which uses a querySelector to select specific content.

  • Refetching: Content can be refetched by clicking a link or by using a <button command="--load"> element. The Refresh header or <meta http-equiv=refresh> tag in the response can also trigger a refresh.

  • Content Negotiation: The accept= attribute allows customization of the Accept header in the request, limited to text/plain, text/html, image/svg+xml, and application/xml. Invalid MIME types default to text/html.

  • Streaming: With accept="text/event-stream", <i-html> uses EventSource to listen for Server-Side Events, allowing for multiple content updates with a single request.

  • Insertion Modes: Content can be appended (insert="append") or prepended (insert="prepend") to existing content instead of replacing it.

  • Deferring Loading: The loading= attribute can be set to lazy to defer loading until the element is visible, or to none to prevent loading until changed via JavaScript. A <button command="--load"> can force loading regardless of the loading attribute.

  • Security: <i-html> uses fetch() and adheres to CORS policies. By default, it only fetches same-origin URLs. The allow="cross-origin" attribute allows cross-origin requests. Several elements, such as <iframe>, <script>, and <style> are sanitized out by default, unless specifically allowed with the allow attribute.

  • Declarative Shadow DOM: <i-html> supports declarative shadow DOM (DSD) if the browser supports Document.parseHTMLUnsafe. Older browsers require a polyfill.

  • Styling: The element has pseudo-classes (:waiting, :loading, :loaded, and :error) for styling during different stages of its lifecycle, and uses attributes like [state-waiting] in older browsers.

  • Events: <i-html> dispatches events such as loadstart, load, loadend, error, beforeinsert, and inserted during its lifecycle. The loadstart event can be used to customize the request or prevent loading. The beforeinsert event can modify or prevent content insertion.

<i-html> aims to combine the best features of similar elements, like include-fragment, and offers more functionality than other options like htmx or htmz. It remains in the DOM and can refetch content, unlike <include-fragment> which replaces itself.