The
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.