Repository: keithamus/i-html
Branch: main
Commit: 6eedf0268e77
Files: 23
Total size: 60.8 KB
Directory structure:
gitextract_zvnutdbd/
├── .github/
│ └── workflows/
│ ├── publish.yml
│ └── static.yml
├── .gitignore
├── README.md
├── example-responses/
│ ├── ajax-form.html
│ ├── dsd.html
│ ├── empty.html
│ ├── form-delete.html
│ ├── form-save.html
│ ├── hello.html
│ ├── how-are-you.html
│ ├── lazy.html
│ ├── prepend-list.html
│ ├── refresh-tock.html
│ ├── refresh.html
│ ├── sanitization.html
│ ├── theme-gray.html
│ ├── theme-pink.html
│ ├── theme-yellow.html
│ └── two-paragraphs.html
├── i-html.js
├── index.html
└── package.json
================================================
FILE CONTENTS
================================================
================================================
FILE: .github/workflows/publish.yml
================================================
name: Publish
on:
release:
types: [created]
jobs:
publish-npm:
name: Publish to npm
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with:
node-version: 24
registry-url: https://registry.npmjs.org/
cache: npm
- run: npm install -g npm@latest
- run: npm install
- run: npm run build --if-present
- run: npm version ${TAG_NAME} --git-tag-version=false
env:
TAG_NAME: ${{ github.event.release.tag_name }}
- run: npm publish --provenance --access public
================================================
FILE: .github/workflows/static.yml
================================================
# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages
on:
# Runs on pushes targeting the default branch
push:
branches: ["main"]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
# Single deploy job since we're just deploying
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
# Upload entire repository
path: '.'
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
================================================
FILE: .gitignore
================================================
node_modules
i-html.min.js
================================================
FILE: README.md
================================================
## i-html
[i-html](https://github.com/keithamus/i-html) is a drop in tag that allows for dynamically _importing_ html,
_inline_. It's a bit like an `<iframe>`, except the html gets adopted into the page.
[Visit the website to learn more](https://keithcirkel.co.uk/i-html).
================================================
FILE: example-responses/ajax-form.html
================================================
<!DOCTYPE html>
<html>
<body>
<form
action="example-responses/ajax-form.html"
method="get"
target="ajax-form-target-example"
>
<label>A form label:
<input type="search" />
</label>
<button type="submit">Submit</button>
</form>
<p>
Something would have saved to a server if I had stretched to pay for one,
but you'll just have to believe me.
</p>
</body>
</html>
================================================
FILE: example-responses/dsd.html
================================================
<!DOCTYPE html>
<html>
<body>
<div>
<template shadowrootmode="open">
<p><slot></slot></p>
<style>
:host {
font-family: Georgia, Times, 'Times New Roman', serif;
font-style: italic;
border-block-end: 2px dashed currentColor;
}
</style>
</template>
This will be formatted according to the stylesheet in shadow DOM.
</div>
</body>
</html>
================================================
FILE: example-responses/empty.html
================================================
<!DOCTYPE html>
<html>
<body>
<span></span>
</body>
</html>
================================================
FILE: example-responses/form-delete.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>Whatever was saved has now been deleted.</p>
</body>
</html>
================================================
FILE: example-responses/form-save.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>Your form would have been saved if I was't too cheap to spring for a server.</p>
</body>
</html>
================================================
FILE: example-responses/hello.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>Hello world!</p>
</body>
</html>
================================================
FILE: example-responses/how-are-you.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>How are you?</p>
</body>
</html>
================================================
FILE: example-responses/lazy.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>This loaded in very lazily... but you might not have seen (try looking in network devtools)</p>
</body>
</html>
================================================
FILE: example-responses/prepend-list.html
================================================
<!DOCTYPE html>
<html>
<body>
<ul>
<li>Butter</li>
</ul>
</body>
</html>
================================================
FILE: example-responses/refresh-tock.html
================================================
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="1;url=refresh.html">
</head>
<body>
<p>Tock!</p>
</body>
</html>
================================================
FILE: example-responses/refresh.html
================================================
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="refresh" content="1;url=refresh-tock.html">
</head>
<body>
<p>Tick!</p>
</body>
</html>
================================================
FILE: example-responses/sanitization.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>This response contained an <code><i-html></code> element, but it was sanitized out!</p>
<i-html>You should not see this!</i-html>
<p>This repsonse also contained an image of a cat. This was explicitly allowed!</p>
<img src="https://placecats.com/150/150"/>
</body>
</html>
================================================
FILE: example-responses/theme-gray.html
================================================
<!DOCTYPE html>
<html>
<body>
<style>
:root {
--background: #f6f8fa !important;
--color: #1f2328 !important;
--link-color: #393f46 !important;
--link-visited-color: #59636e !important;
--border-color: #dae0e7 !important;
}
</style>
</body>
</html>
================================================
FILE: example-responses/theme-pink.html
================================================
<!DOCTYPE html>
<html>
<body>
<style>
:root {
--background: #fff0f6 !important;
--color: #a61e4d !important;
--link-color: #364fc7 !important;
--link-visited-color: #5f3dc4 !important;
--border-color: #a61e4d !important;
}
</style>
</body>
</html>
================================================
FILE: example-responses/theme-yellow.html
================================================
<!DOCTYPE html>
<html>
<body>
<style>
:root {
--background: #fff9db !important;
--color: #d9480f !important;
--link-color: #364fc7 !important;
--link-visited-color: #5f3dc4 !important;
--border-color: #e67700 !important;
}
</style>
</body>
</html>
================================================
FILE: example-responses/two-paragraphs.html
================================================
<!DOCTYPE html>
<html>
<body>
<p>
This was the first paragraph from the response.
</p>
<p>
This was the second paragraph from the response.
</p>
</body>
</html>
================================================
FILE: i-html.js
================================================
// A small polyfill for CSSStateSet
class StateSet extends Set {
#el = null
#existing = null
constructor(el, existing) {
super()
this.#el = el
this.#existing = existing
}
add(state) {
super.add(state)
const existing = this.#existing
if (existing) {
try {
existing.add(state)
} catch {
existing.add(`--${state}`)
}
} else {
this.#el.setAttribute(`state-${state}`, '')
}
}
delete(state) {
super.delete(state)
const existing = this.#existing
if (existing) {
existing.delete(state)
existing.delete(`--${state}`)
} else {
this.#el.removeAttribute(`state-${state}`)
}
}
has(state) {
return super.has(state)
}
clear() {
for(const state of this) this.delete(state)
}
}
const queueATask = () => new Promise(resolve => setTimeout(resolve, 0))
const styles = new CSSStyleSheet()
styles.replace(`
:host {
display: contents;
}
`)
export class RequestEvent extends Event {
request = null
constructor(request) {
super('loadstart', {})
this.request = request
}
}
export class InsertEvent extends Event {
content = null
constructor(name, content, init) {
super(name, init)
this.content = content
}
}
function handleLinkTargets(event) {
const el = event.target.closest('a[target]')
const base = event.target.ownerDocument.head.querySelector('base[target]')
const target = el && el.target ? document.getElementById(el.target) : base && base.target ? document.getElementById(base.target) : null
if (!target || !(target instanceof IHTMLElement)) return
target.src = el.href
event.preventDefault()
}
const textMime = /^text\/([^+]+\+)?plain\s*(?:;.*)?$/
const htmlMime = /^text\/([^+]+\+)?html\s*(?:;.*)?$/
const svgMime = /^image\/(svg\+)xml\s*(?:;.*)?$/
const xmlMime = /^application\/([^+]+\+)?xml\s*(?:;.*)?$/
const eventStreamMime = /^text\/([^+]+\+)?event-stream\s*(?:;.*)?$/
const wildcardMime = /^\*\/(?:[^+]+\+)?\*\s*(?:;.*)?$/
const validAllow = new Set(['refresh', 'iframe', 'i-html', 'media', 'script', 'style', 'cross-origin'])
export class IHTMLElement extends HTMLElement {
static observedAttributes = ['src', 'accept', 'loading', 'allow']
get src() {
return new URL(this.getAttribute('src') || '', window.location.href).toString()
}
set src(val) {
this.setAttribute('src', val)
}
get credentials(){
let credentials = this.getAttribute('credentials')
if (credentials == 'include' || credentials == 'omit') return credentials
return 'same-origin'
}
set credentials(value) {
this.setAttribute(credentials, value)
}
get #defaultTarget() {
if (svgMime.test(this.accept)) return 'svg'
return 'body > *'
}
get target() {
const target = this.getAttribute('target') || this.#defaultTarget
try {
this.matches(target)
return target
} catch {
return this.#defaultTarget
}
}
set target(value) {
this.setAttribute('target', value)
}
#allow = new Set()
get allow() {
return Array.from(this.#allow).join(' ')
}
set allow(value) {
this.setAttribute('allow', value)
if (value == '*') value = [...validAllow].join(' ')
this.#allow = new Set(String(value).split(/ /g).filter(allow => validAllow.has(allow)))
}
get insert() {
const insert = this.getAttribute('insert')
if (insert === 'append') return 'append'
if (insert === 'prepend') return 'prepend'
return 'replace'
}
set insert(value) {
this.setAttribute('insert', value)
}
get loading() {
if (this.getAttribute('loading') === 'lazy') return 'lazy'
if (this.getAttribute('loading') === 'none') return 'none'
return 'eager'
}
set loading(value) {
this.setAttribute('loading', value)
}
get accept() {
const accept = this.getAttribute('accept') || ''
if (textMime.test(accept)) return accept
if (htmlMime.test(accept)) return accept
if (svgMime.test(accept)) return accept
if (xmlMime.test(accept)) return accept
if (wildcardMime.test(accept)) return accept
return 'text/html'
}
set accept(val) {
this.setAttribute('accept', val)
}
#internals = this.attachInternals()
#fetchController = new AbortController()
#observer = new IntersectionObserver(
entries => {
for (const entry of entries) {
if (entry.isIntersecting) {
const {target} = entry
this.#observer.unobserve(target)
if (!this.shadowRoot.contains(target)) return
if (this.loading === 'lazy') {
this.#load()
}
}
}
},
{
// Currently the threshold is set to 256px from the bottom of the viewport
// with a threshold of 0.1. This means the element will not load until about
// 2 keyboard-down-arrow presses away from being visible in the viewport,
// giving us some time to fetch it before the contents are made visible
rootMargin: '0px 0px 256px 0px',
threshold: 0.01,
},
)
constructor() {
super()
Object.defineProperty(this.#internals, 'states', {value: new StateSet(this, this.#internals.states)})
if (!this.shadowRoot) {
this.attachShadow({mode: 'open'})
this.shadowRoot.adoptedStyleSheets.push(styles)
this.shadowRoot.append(document.createElement('slot'))
this.shadowRoot.append(document.createElement('span'))
}
this.#internals.states.add('waiting')
this.#internals.role = 'presentation'
}
attributeChangedCallback(name, old, value) {
if (name === 'src' || name === 'accept') {
if (this.isConnected && this.loading === 'eager') {
this.#load()
} else if (this.loading !== 'eager') {
this.#fetchController?.abort()
}
} else if (name === 'loading') {
if (this.isConnected && old !== 'eager' && value === 'eager') {
this.#load()
} else if (this.isConnected && value === 'lazy') {
this.#observe()
}
} else if (name === 'allow') {
this.#allow = new Set(String(value).split(/ /g).filter(allow => validAllow.has(allow)))
}
}
connectedCallback() {
if (this.src && this.loading === 'eager') {
this.#load()
}
this.#observe()
this.addEventListener('command', this)
this.ownerDocument.addEventListener('click', handleLinkTargets, true)
this.ownerDocument.addEventListener('submit', this, true)
}
handleEvent(event) {
if (event.type == 'command') {
if (event.command == '--load') {
this.#load()
} else if (event.command == '--stop') {
clearTimeout(this.#refreshTimer)
this.#fetchController?.abort('stop')
}
} else if (event.type === 'submit') {
const form = event.target
if (form.tagName !== 'FORM') return
const base = form.ownerDocument.head.querySelector('base[target]')
const targetId = form.target || base?.target
if (document.getElementById(targetId) !== this) return
const action = event.submitter.getAttribute('formaction') || form.action
const method = (event.submitter.getAttribute('formmethod') || form.method || 'GET').toUpperCase()
const formData = new FormData(form)
if (method === 'GET') {
const url = new URL(action, window.location.href)
url.search = new URLSearchParams(formData).toString()
this.src = url.toString()
} else {
this.#load(action, {method, body: new URLSearchParams(formData)})
}
event.preventDefault()
}
}
disconnectedCallback() {
this.#fetchController?.abort('disconnected')
}
#observe() {
this.#observer.observe(this.shadowRoot.querySelector('span'))
}
#refreshTimer = null
#setupRefresh(refresh) {
if (!this.#allow.has('refresh')) return
let [time, url] = String(refresh).split(/;\s*url=/) || []
time = time ? Number(time) : -1
clearTimeout(this.#refreshTimer)
if (time > -1 && time < Number.MAX_SAFE_INTEGER) {
this.#refreshTimer = setTimeout(() => this.#load(url), Number(time) * 1000)
}
}
async #load(src, options) {
if (!src && !this.hasAttribute('src')) return
src = new URL(src || this.src, this.src || window.location.href)
if (!this.#allow.has('cross-origin') && src.origin !== window.location.origin) {
console.log(src, window.location.origin);
throw new Error(`i-html failed to load cross origin resource ${src} without allow=cross-origin`)
}
if (!options && !this.#fetchController?.signal.aborted && this.#fetchController?.src == src.toString()) return
clearTimeout(this.#refreshTimer)
this.#fetchController.abort()
this.#fetchController = new AbortController()
this.#fetchController.src = src.toString()
this.#internals.states.delete('error')
this.#internals.states.delete('waiting')
this.#internals.states.add('loading')
// We mimic the same event order as <img>, including the spec
// which states events must be dispatched after "queue a task".
// https://www.w3.org/TR/html52/semantics-embedded-content.html#the-img-element
await queueATask()
let error = false
try {
const method = options?.method || 'GET'
const fetchOptions = {
method,
credentials: this.credentials,
headers: {
Accept: this.accept,
},
}
if (options?.body) {
fetchOptions.body = options.body
fetchOptions.headers['Content-Type'] = 'application/x-www-form-urlencoded'
}
const request = new RequestEvent(new Request(src, fetchOptions))
if (eventStreamMime.test(this.accept)) {
await this.#stream(request.request)
} else {
await this.#loadOnce(request.request)
}
} catch (e) {
error = e
} finally {
this.#fetchController.abort()
// We mimic the same event order as <img>, including the spec
// which states events must be dispatched after "queue a task".
// https://www.w3.org/TR/html52/semantics-embedded-content.html#the-img-element
await queueATask()
this.#internals.states.delete('loading')
this.#internals.states.delete('streaming')
this.#internals.states.add(error ? 'error' : 'loaded')
this.dispatchEvent(new Event(error ? 'error' : 'load'))
this.dispatchEvent(new Event('loadend'))
if (error) throw error
}
}
async #stream(request) {
const source = new EventSource(request.src)
this.#fetchController.signal.addEventListener('abort', () => {
source.close()
})
let open = false
source.addEventListener('message', e => {
if (!open) return
this.#parseAndInject(message.data, 'text/html')
})
await new Promise((resolve, reject) => {
source.addEventListener('open', resolve, {once: true})
source.addEventListener('error', reject, {once: true})
})
open = true
this.dispatchEvent(new Event('open'))
this.#internals.states.delete('loading')
this.#internals.states.add('streaming')
await new Promise((resolve, reject) => {
source.addEventListener('close', resolve, {once: true})
source.addEventListener('error', reject, {once: true})
})
}
async #loadOnce(request) {
const signal = this.#fetchController.signal
let response
try {
response = await fetch(request, {signal})
} catch (e) {
if (e.code == DOMException.ABORT_ERR) return
throw e
}
if (!response) {
throw new Error(`Failed to load response`)
}
this.#setupRefresh(response.headers.get('Refresh') || '')
const ct = response.headers.get('Content-Type') || ''
const accept = this.accept
if (!wildcardMime.test(accept)) {
let ctParts = (ct.match(htmlMime) || ct.match(textMime) || ct.match(xmlMime) || ct.match(svgMime) || [])[1]
let acceptParts = (accept.match(htmlMime) || accept.match(xmlMime) || accept.match(svgMime) || [])[1]
if (ctParts && ctParts !== acceptParts) {
throw new Error(`Failed to load resource: expected ${accept} but was ${ct}`)
}
}
let resolvedCt = htmlMime.test(ct) ? 'text/html' : textMime.test(ct) ? 'text/plain' : xmlMime.test(ct) ? 'application/xml' : svgMime.test(ct) ? 'image/svg+xml' : null
if (!resolvedCt) {
throw new Error(`Failed to load resource: expected mime to be like 'text/html', 'application/xml' or 'image/svg+xml', but got ${ct || '(empty string)'}`)
}
this.#parseAndInject(await response.text(), resolvedCt)
}
#parseAndInject(responseText, mime) {
let children;
if (mime == 'text/plain') {
const doc = new DOMParser().parseFromString('<!DOCTYPE html>', 'text/html')
const span = document.createElement('span')
span.textContent = responseText;
doc.body.append(span)
children = doc.querySelectorAll('span')
} else {
let doc
if (mime == 'text/html' && 'parseHTMLUnsafe' in Document) {
doc = Document.parseHTMLUnsafe(responseText)
} else {
doc = new DOMParser().parseFromString(responseText, mime)
}
this.#setupRefresh(doc.querySelector('meta[http-equiv="refresh"]')?.content || '')
children = this.#sanitize(doc).querySelectorAll(this.target)
}
const beforeInsert = new InsertEvent('beforeinsert', children, { cancelable: true })
const shouldContinue = this.dispatchEvent(beforeInsert) && children.length
if (!shouldContinue) {
return
}
const oldActiveElement = this.ownerDocument.activeElement
if (this.insert === 'append') {
this.append(...beforeInsert.content)
} else if (this.insert === 'prepend') {
this.prepend(...beforeInsert.content)
} else {
this.replaceChildren(...beforeInsert.content)
}
const activeElement = this.ownerDocument.activeElement
if (activeElement != oldActiveElement) {
activeElement.focus({ preventScroll: true })
}
this.dispatchEvent(new InsertEvent('inserted', this.childNodes))
}
#sanitize(doc) {
let removes = []
const allows = this.#allow
if (!allows.has('iframe')) removes.push('iframe')
if (!allows.has('i-html')) removes.push('i-html')
if (!allows.has('script')) removes.push('script')
if (!allows.has('style')) removes.push('style', 'link[rel=stylesheet]')
if (!allows.has('media')) removes.push('img', 'picture', 'video', 'audio', 'object')
if (removes.length) {
for(const el of doc.querySelectorAll(removes.join(', '))) el.remove()
}
return doc
}
}
customElements.define('i-html', IHTMLElement)
================================================
FILE: index.html
================================================
<!doctype html>
<html lang="en">
<head>
<title>i-html, an inline-html import element</title>
<meta name="viewport" content="width=device-width,initial-scale=1" />
<script type="module" src="./i-html.js"></script>
<script type="module" src="https://unpkg.com/invokers-polyfill@0.4.2/invoker.js"></script>
<style>
:root {
--background: #e7ecec;
--color: #262a2a;
--link-color: #3566b8;
--link-visited-color: #7652ac;
--border-color: #8d9292;
}
html {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
max-width: 70ch;
margin: auto;
line-height: 1.5;
font-size: 1.125em;
overflow-wrap: break-word;
background: var(--background);
color: var(--color);
}
a { color: var(--link-color) }
a:visited { color: var(--link-visited-color) }
p {
max-width: 70ch;
margin: 0.5rem 0;
}
h1, h2, h3, h4 {
margin: 2rem 0 0 0;
}
.demo {
border: 1px solid var(--border-color);
border-radius: 8px;
max-width: 70ch;
min-height: 1ch;
padding: 1rem;
}
mark {background:#ead79b}
mark[a] {background:#a5e9ca}
mark[b] {background:#d1d1ff}
@media (prefers-color-scheme: dark) {
:root {
--background: #232626;
--color: #cacfcf;
--link-color: #3b86ff;
--link-visited-color: #a167f1;
--border-color: #8d9292;
}
}
</style>
</head>
<body>
<main>
<h1>i-html</h1>
<p>
<a href="https://github.com/keithamus/i-html">i-html</a> is a drop in
tag that allows for dynamically <em>importing</em> html,
<em>inline</em>. It's a bit like an <code><iframe></code>, except the
html gets adopted into the page.
</p>
<p>
You might have used something similar before, it might seem familiar to
other techniques such as
<a href="https://turbo.hotwired.dev/">hotwired turbo</a> or similar. You
might have even used an element very close to this one, for example the
popular
<a href="https://github.com/github/include-fragment-element"
>include-fragment-element</a
>
by GitHub. This element is a spiritual successor to that one (more on
that below). But this one is <code><i-html></code>. Let's talk about
it.
</p>
<p>
Inside the box below is a demonstration of the element. The box is there
to help you see it, but the element is inside. If JavaScript is enabled
the contents of the box should read "Hello world!". The source page is
just an HTML page. There's nothing special about it. Look, go see for
yourself: <a href="example-responses/hello.html">hello.html</a>.
</p>
<pre>
<code>
<i-html <mark>src="example-responses/hello.html"</mark>>Loading...</i-html>
</code>
</pre>
<div class="demo">
<i-html src="example-responses/hello.html">Loading...</i-html>
</div>
<p>
The <code><i-html></code> tag can be placed on a page, as an empty
container. It is completely unstyled (well almost, it has
<code>display:contents</code>). Whenever the <code>src=</code> attribute
changes, it will fetch the requested resource as
<code>text/html</code> and replace its inner contents with the parsed
contents of the response. That's essentially all it does. Kind of.
</p>
<p>
Setting <code>src=</code> and leaving it alone does not really
demonstrate the full utility, however, because it is far more capable of
interesting things when utilised correctly. People do lots of novel
things with <code><img></code> tags, and <code><i-html></code>
should be no different.
</p>
<h2 id="getting-started">Getting started</h2>
<p>
The easiest way to start is to include the minified script from the CDN:
</p>
<pre>
<code>
<script src="https://cdn.jsdelivr.net/npm/i-html-element/i-html.min.js" defer></script>
</code>
</pre>
<p>
or run <code>npm i i-html-element</code> and use the local module:
</p>
<pre>
<code>
<script type="module" src="node_modules/i-html-element/i-html.js"></script>
</code>
</pre>
<h2 id="features">Features</h2>
<h3 id="link-target">Targeting with link</h3>
<p>
Like an iframe, <code><i-html></code> respects the
<code>target=</code> attribute on links. If an
<code><a target=></code> points to the <code><i-html></code>, then
the <code>src=</code> is switched with that of the link. A
demonstration:
</p>
<pre>
<code>
<a href="example-responses/hello.html" <mark>target="link-target-example"</mark>>
Load hello.html
</a>
<a href="example-responses/how-are-you.html" <mark>target="link-target-example"</mark>>
Load how-are-you.html
</a><br>
<i-html <mark>id="link-target-example"</mark>></i-html>
</code>
</pre>
<div class="demo">
<a href="example-responses/hello.html" target="link-target-example">
Load hello.html
</a>
<a href="example-responses/how-are-you.html" target="link-target-example">
Load how-are-you.html
</a><br>
<i-html id="link-target-example"></i-html>
</div>
<h3 id="form-target">Targeting with form</h3>
<p>
Also like an iframe, <code>target=</code> on forms is also respected.
This means forms can submit to an <code><i-html></code> element which
will then load in new content. Here's a dummy form, for example:
</p>
<pre>
<code>
<form action="example-responses/form-save.html" method="get" <mark>target="form-target-example"</mark>>
<label>
A form label:
<input type="search" />
</label>
<button type="submit">Submit</button>
</form>
<p>Submitting the form will change the content below:</p>
<i-html <mark>id="form-target-example"</mark>>Nothing yet</i-html>
</code>
</pre>
<div class="demo">
<form action="example-responses/form-save.html" method="get" target="form-target-example">
<label>
A form label:
<input type="search" />
</label>
<button type="submit">Submit</button>
</form>
<p>Submitting the form will change the content below:</p>
<i-html id="form-target-example">Nothing yet</i-html>
</div>
<h3 id="form-wrap">Wrapping a form</h3>
<p>
Wrap a <code><form></code> tag in an <code><i-html></code> element
and you'll have a form that replaces itself. Serve the same form back
and you have an "AJAX style" form with no effort.
</p>
<pre>
<code>
<i-html <mark>id="ajax-form-target-example"</mark>>
<form action="example-responses/ajax-form.html" method="get" <mark>target="ajax-form-target-example"</mark>>
<label>
A form label:
<input type="search" />
</label>
<button type="submit">Submit</button>
</form>
<p>Submitting the form will change the whole form</p>
</i-html>
</code>
</pre>
<div class="demo">
<i-html id="ajax-form-target-example">
<form action="example-responses/ajax-form.html" method="get" target="ajax-form-target-example">
<label>
A form label:
<input type="search" />
</label>
<button type="submit">Submit</button>
</form>
<p>Submitting the form will change the whole form</p>
</i-html>
</div>
<h3 id="form-actions">Form actions</h3>
<p>
Of course because <code><forms></code> work, so does
<code><button formaction=</code>. Example:
</p>
<pre>
<code>
<form method="get" <mark>target="formaction-example"</mark>>
<button <mark a>formaction="example-responses/form-delete.html"</mark> type="submit">
Delete
</button>
<button <mark a>formaction="example-responses/form-save.html"</mark> type="submit">
Save
</button>
</form>
<p>Submitting the form will change the content below:</p>
<i-html <mark>id="formaction-example"</mark>>Nothing yet</i-html>
</code>
</pre>
<div class="demo">
<form method="get" target="formaction-example">
<button formaction="example-responses/form-delete.html" type="submit">
Delete
</button>
<button formaction="example-responses/form-save.html" type="submit">
Save
</button>
</form>
<p>Submitting the form will change the content below:</p>
<i-html id="formaction-example">Nothing yet</i-html>
</div>
<h3 id="targeting-response">Targeting the response</h3>
<p>
By default <code><i-html></code> will parse the response as HTML,
and inject the <code><body></code> element's contents into itself,
ignoring any unwrapped text nodes. The selection of content to be
injected can be customized by setting the <code>target=</code> attribute
on <code><i-html></code> itself (which defaults to <code>'body>*'</code>
(or <code>'svg'</code> if <code>accept=</code> is an SVG mime)). If you
find you want to take a different element from the response body, set
<code>target=</code> to any valid <code>querySelector</code>. If
<code>target=</code> is an invalid <code>querySelector</code> it'll
revert to <code>'body>*'</code>. You can check if a
<code>target=</code> select is valid by using JavaScript to set
<code>.target</code> and then read the value back out, for example:
</p>
<pre>
<code>
myEl.target = '/not a valid selector/' // this won't set:
console.assert(myEl.target === 'body')
myEl.accept = '.this[is]:valid' // this will set:
console.assert(myEl.target === '.this[is]:valid')
</code>
</pre>
<p>
In the below example, these two links fetch the same HTML, which has two
paragraphs. However the two links target two different
<code><i-html></code> elements, the first one with a
<code>target="p:first-child"</code>, the second with a
<code>target="p:last-child"</code>.
</p>
<pre>
<code>
<a href="example-responses/two-paragraphs.html" <mark>target="two-paragraphs-a"</mark>>
Load two-paragraphs.html into first target
</a>
<a href="example-responses/two-paragraphs.html" <mark>target="two-paragraphs-b"</mark>>
Load two-paragraphs.html into first target
</a>
<p><i-html <mark>id="two-paragraphs-a"</mark> <mark a>target="p:first-child"</mark>></i-html></p>
<p><i-html <mark>id="two-paragraphs-b"</mark> <mark a>target="p:last-child"</mark>></i-html></p>
</code>
</pre>
<div class="demo">
<a href="example-responses/two-paragraphs.html" target="two-paragraphs-a">
Load two-paragraphs.html into first target
</a>
<a href="example-responses/two-paragraphs.html" target="two-paragraphs-b">
Load two-paragraphs.html into first target
</a>
<p><i-html id="two-paragraphs-a" target="p:first-child"></i-html></p>
<p><i-html id="two-paragraphs-b" target="p:last-child"></i-html></p>
</div>
<h3 id="re-fetching">Refetching</h3>
<p>
If you want to refetch the contents there are several options. The
simplest is to use an <code><a href></code> element, as clicking the
link will cause <code><i-html></code> to load each time.
</p>
<p>
That's not always the easiest though, and so another option is to use a
<code><button command="--load" commandfor=".."></code> element,
which will cause the <code><i-html></code> to load the
<code>src</code> it has (regardless of the <code>loading=</code> value,
see <a href="#deferring-loading">Deferring Loading</a> for more on
that).
</p>
<details>
<summary>(For older browsers that don't support command/commandfor buttons)</summary>
<p>
You'll need to drop in the "invokers-polyfill" package to polyfill
this in older browsers.
</p>
<pre><code>
<script type="module" src="https://unpkg.com/invokers-polyfill@0.4.2/invoker.js">
</script>
</code></pre>
</details>
<pre>
<code>
<button <mark>command="--load" commandfor="command-load-example"</mark>>Load</button>
<i-html <mark>id="command-load-example"</mark> src="example-responses/hello.html"></i-html>
</code>
</pre>
<div class="demo">
<button command="--load" commandfor="command-load-example">Load</button>
<i-html id="command-load-example" src="example-responses/hello.html"></i-html>
</div>
<p>
Responses can indicate to the client when the content should refresh by
adding a `Refresh` header (or a <code><meta http-equiv=refresh></code>
meta tag), telling <code><i-html></code> to refresh after N seconds.
This is <em>opt-in</em> though, and needs the <code>allow=refresh</code>
attribute on the element.
</p>
<p>
The `Refresh` header can also have a URL to traverse to. This is also
respected, which can make for some interesting properties such as the
example below. Lastly, this can be stopped with
<code><button command="--stop"</code>:
</p>
<pre>
<code>
<button <mark>command="--stop" commandfor="refresh-example"</mark>>Stop</button>
<i-html <mark b>allow="refresh"</mark> <mark>id="refresh-example"</mark> src="example-responses/refresh.html"></i-html>
</code>
</pre>
<div class="demo">
<button command="--stop" commandfor="refresh-example">Stop</button>
<i-html allow="refresh" loading="lazy" id="refresh-example" src="example-responses/refresh.html"></i-html>
</div>
<h3 id="content-negotiation">Content negotiation</h3>
<p>
By default <code><i-html></code> will make a request using the header
<code>Accept: text/html</code>. You can customise this by setting the
<code>accept=</code> attribute, but it is limited to certain values:
</p>
<ul>
<li><code>text/plain</code>.</li>
<li><code>text/html</code>.</li>
<li><code>image/svg+xml</code>.</li>
<li><code>application/xml</code>.</li>
</ul>
<p>
You can slightly customise these types by setting the "subtype combination"
or "parameter values", and it'll be smart and make the request with those
extras. This means <code>application/xhtml+xml</code> will work, and the
expected return content-type must be either <code>application/xml</code> or
<code>application/xhtml+xml</code> (but an entirely different sub-type like
<code>application/atom+xml</code> will fail). Also more complex mime
types like <code>text/fragment+html; charset=utf-8</code> will work, and
the server can respond with the generic <code>text/html</code> or the matching
sub-type of <code>text/fragment+html</code>.
</p>
<p>
Invalid mimes such as <code>application/json</code> will revert to
<code>text/html</code>. (If you want to get JSON you don't need this element).
</p>
<p>
You can check what type works by using JavaScript to set <code>.accept</code>
and then read the value back out, for example:
</p>
<pre>
<code>
myEl.accept = 'application/json' // this won't set:
console.assert(myEl.accept === 'text/html')
myEl.accept = 'text/fragment+html; charset=utf-8' // this will set:
console.assert(myEl.accept === 'text/fragment+html; charset=utf-8')
</code>
</pre>
<p>
The mime types <code>text/html</code>, <code>image/svg+xml</code>, and
<code>application/xml</code> will all use <code>DOMParser</code> to
parse the full response body. <code>text/event-stream</code> uses a
different streaming mode...
</p>
<pre>
<code>
<a href="star-solid.svg" <mark>target="svg-example"</mark>>
<i-html <mark>id="svg-example"</mark> src="example-responses/star.svg" <mark a>accept="image/svg+xml"</mark>></i-html>
</a>
</code>
</pre>
<div class="demo">
<center>
<a href="example-responses/star-solid.svg" target="svg-example">
<i-html id="svg-example" src="example-responses/star.svg" accept="image/svg+xml"></i-html>
</a>
</center>
</div>
<h3 id="streaming-mode">Streaming Mode</h3>
<p>
With the <code>accept=</code> attribute set to
<code>text/event-stream</code>, it will use an
<code>EventSource</code> to listen for
<a
href="https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events"
>Server-Side Events</a
>. A connection will be open and for each event fired, the response will
be converted using <code>DOMParser</code> and replaced. This allows for
many replacements with one request (this could be useful, for example,
to show a notification count for a user). The connection will be kept
open and replacing contents until either the server drops out, the
browser closes the <code>EventSource</code>, the element is removed from
the DOM, or the <code>src=</code> or <code>accept=</code> attributes
change value.
</p>
<h3 id="insertion-mode">Insertion Mode</h3>
<p>
Whether in streaming mode or one-shot mode, the default operation is to
replace the contents of the element with the newly downloaded contents.
While this is useful <em>most of the time</em>, some of the time it can
be even more useful to switch to an append mode. Changing to
<code>insert=append</code> will cause new content to be added after all
the current children, and using <code>insert=prepend</code> will cause
new content to be added before the current children:
</p>
<pre>
<code>
<a href="example-responses/prepend-list.html" <mark>target="prepend-example"</mark>>
Prepend to this list:
</a>
<ul>
<i-html <mark>id="prepend-example"</mark> <mark a>target="li"</mark> <mark b>insert="prepend"</mark>>
<li>Milk</li>
<li>Eggs</li>
</i-html>
</ul>
</code>
</pre>
<div class="demo">
<a href="example-responses/prepend-list.html" target="prepend-example">
Prepend to this list:
</a>
<ul>
<i-html id="prepend-example" target="li" insert="prepend">
<li>Milk</li>
<li>Eggs</li>
</i-html>
</ul>
</div>
<h3 id="deferring-loading">Deferring Loading</h3>
<p>
Just like <code><img></code> and <code><iframe></code> tags,
<code><i-html></code> tags have a <code>loading=</code> attribute. By
default they are <code>loading=eager</code>, but changing it to
<code>loading=lazy</code> means it will wait until it's visible in the
viewport until it makes the request. This also respects CSS styles, so
if it's inside an element with <code>display:none</code> then
<code>loading=lazy</code> can prevent it from loading until its
container is <code>display:block</code>. This is really handy for
components like <code><dialog></code>s.
</p>
<p>
Changing to <code>loading=none</code> means it will <em>never load</em>,
unless the <code>loading=</code> attribute is changed back to either
<code>loading=eager</code> or <code>loading=lazy</code>. This gives you
an opportunity to use JavaScript to determine when the loading should
occur, for example on click.
</p>
<p>
A <code><button command="--load" commandfor=".."></code> element
pointing to a, <code><i-html></code> element will force it to load,
regardless of the <code>loading=</code> value.
</p>
<div class="demo">
<i-html id="lazy-example" loading="lazy" src="example-responses/lazy.html">
... lazy loading ...
</i-html>
</div>
<h3 id="security">Security</h3>
<p>
Injecting arbitrary HTML into a page can pose some security risks, so
it's important that there's a <em>defence in depth</em> approach to
mitigating the risk surface area. <code><i-html></code> has some
security provisions in place but it's important to not only lean on
these, and also apply additional security measures:
</p>
<ul>
<li>
Use a <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP">
Content Security Policy
</a>. A good minimum default is <code>script-src self</code>, which
will prevent JavaScript from executing unless it's served by the same
origin, and only from <code><script></code> tags, not inline
attributes such as <code>onclick</code>.
</li>
<li>
Consider how to <a href="https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html">
protect against CSRF
</a>. A good measure would be HTTP-only session cookies to protect
sensitive resources.
</li>
<li>
Fine tune your <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS">
CORS policies
</a> to protect against injecting pages you might not want
<code><i-html></code> to embed.
</li>
</ul>
<p>
With that out of the way, let's talk about the protections
<code><i-html></code> has in place. It uses <code>fetch()</code>
under-the-hood and so must adhere to CORS policies. By default the
<code>credentials</code> option is set to <code>'same-origin'</code>
meaning it will send cookies (and respect the <code>Set-Cookie</code>
response header) for same-orign requests. To lock this down further
setting <code>credentials="omit"</code> will never send/recieve cookies,
and setting <code>credentials="include"</code> will open it up to
sending/receiving cookies in cross-origin requests.
</p>
<p>
The default behaviour of <code><i-html></code> is restricted in some
ways, and these restrictions can be lifted by adding keywords into the
<code>allow=</code> attribute. This attribute takes a space-separated
list of well-known keywords, and each one will allow a certain type of
previously restricted behaviour to happen. The keywords can be combined,
so for example <code>allow="refresh media cross-origin"</code> is a
valid value.
</p>
<h4 id="cross-origin">Cross Origin (<code>allow="cross-origin"</code>)</h4>
<p>
The default behaviour of <code><i-html></code> is to <em>only</em>
fetch same-origin URLs. This means
<code><i-html src="https://other-site"></code> won't actually do
anything, as you'll need to allow cross-origin requests explicitly.
This can be done with the <code>allow="cross-origin"</code> attribute.
</p>
<p>
It is important to note that <code>allow="cross-origin"</code> only
impacts the <em>initial fetch</em>. Without
<code>allow="cross-origin"</code> a page may still have URLs or
resources (such as images) to other origins, and these will be rendered
regardless of this setting.
</p>
<h4 id="sanitization">Sanitization</h4>
<p>
<code><i-html></code> will never explicitly append certain elements
into the page, unless you opt in. For example if a response contains an
<code><iframe></code> element, this will simply be deleted before
the contents are injected. If you want <code><iframe></code>
elements to be injected, you'll need to add the
<code>allow="iframe"</code> attribute to the element.
<code><iframe></code>s aren't the only elements that get sanitized.
In fact, there are quite a few. Anything that fetches a sub-resource
will be sanitized out by default, only to be opted in with an
<code>allow=</code> attribute.
</p>
<dl>
<dt><code>allow="iframe"</code></dt>
<dd>
This allows the rendering of <code><iframe></code> elements in the
response body.
</dd>
<dt><code>allow="i-html"</code></dt>
<dd>
This allows the rendering of <code><i-html></code> elements in the
response body.
</dd>
<dt><code>allow="script"</code></dt>
<dd>
This allows the rendering of <code><script></code> elements in the
response body.
</dd>
<dt><code>allow="style"</code></dt>
<dd>
This allows the rendering of <code><style></code> and
<code><link rel=stylesheet</code> elements in the response body.
</dd>
<dt><code>allow="media"</code></dt>
<dd>
This allows the rendering of <code><img></code>,
<code><picture></code>, <code><video></code>,
<code><audio></code>, and <code><object></code>
elements in the response body.
</dd>
</dl>
<pre>
<code>
<i-html <mark>src="example-responses/sanitization.html"</mark> <mark b>allow="media"</mark>></i-html>
</code>
</pre>
<div class="demo">
<i-html src="example-responses/sanitization.html" allow="media"></i-html>
</div>
<pre>
<code>
<a target="theme-switcher" href="example-responses/theme-pink.html">Switch to pink theme</a><br>
<a target="theme-switcher" href="example-responses/theme-yellow.html">Switch to yellow theme</a><br>
<a target="theme-switcher" href="example-responses/theme-gray.html">Switch to grayscale theme</a><br>
<a target="theme-switcher" href="example-responses/empty.html">Reset theme</a><br>
<i-html id="theme-switcher" allow="style"></i-html>
</code>
</pre>
<div class="demo">
<a target="theme-switcher" href="example-responses/theme-pink.html">Switch to pink theme</a><br>
<a target="theme-switcher" href="example-responses/theme-yellow.html">Switch to yellow theme</a><br>
<a target="theme-switcher" href="example-responses/theme-gray.html">Switch to grayscale theme</a><br>
<a target="theme-switcher" href="example-responses/empty.html">Reset theme</a><br>
<i-html id="theme-switcher" allow="style"></i-html>
</div>
<h4 id="turning-off-protections">Tuning off protections</h4>
<p>
Of course, if you like to live dangerously, you can turn all of this off
by setting <code>allow="*"</code>. This is a very bad idea but can be
useful during development.
</p>
<h3 id="dsd">Declarative Shadow DOM</h3>
<p>
Support for parsing fragments of HTML which include declarative shadow DOM (DSD) templates via <code>Document.parseHTMLUnsafe</code> <a href="https://developer.mozilla.org/en-US/docs/Web/API/Document/parseHTMLUnsafe_static">recently entered Baseline 2024 status</a>, so <code><i-html></code> will use that method of parsing if supported. Older browsers would need a polyfill to handle those cases, otherwise, <code><i-html></code> will fall back on <code>new DOMParser().parseFromString</code> which does not support DSD.
</p>
<p>
<strong>Note:</strong> the "unsafe" nomenclature of this API simply means the browser won't perform any sanitization. (Coming soon to the web platform, there will be a `parseHTML` counterpart which does.) But as explained above, <code><i-html></code> will perform its <em>own</em> sanitizing process unless you choose to opt into the various `allow` directives.
</p>
<div class="demo">
<i-html id="dsd-example" loading="lazy" src="example-responses/dsd.html">
... loading dsd ...
</i-html>
</div>
<h3 id="styling">Styling</h3>
<p>
By default this element is <code>display: contents</code> so it won't
effect layout, and it has <code>role=presentation</code> so the
container itself has no impact on the accessibility tree. All of the
content loaded in, however, will effect layout and the accessibility
tree. There are 4 pseudo classes you can use to style it during various
stages of its lifecycle, it will always be in one of these states, and
never more than one. The states are <code>loading</code>,
<code>loaded</code>, <code>errored</code>, and <code>waiting</code>.
They can be styled like so:
</p>
<pre>
<code>
<style style="display:block">
.foo:state(waiting) { background: grey; }
.foo:state(loading) { background: yellow; }
.foo:state(loaded) { background: green; }
.foo:state(error) { background: red; }
</style>
</code>
</pre>
<details>
<summary>(For older browsers that don't support
<a
href="https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet"
>CSS CustomStateSet</a
> you'll need some additional CSS.)</summary>
<p>
The element will fall back to using attributes like
<code>[state-waiting]</code> in older browsers, such as Safari 17.3
and below, Firefox 125 and below, and Chrome 89 and below.
</p>
<p>
Chrome versions 90-124 used a different syntax for <code>:state()</code>,
which used double dashes instead, like <code>:--waiting</code>. There's
a small bit of support code to handle those versions and so it will fall
back to using syntax like <code>:--waiting</code> if it needs to. If you need to
support all of these you'll need something more like:
</p>
<pre><code><style style="display:block">
.foo:where(:state(waiting), :--waiting, [state-waiting]) { background: grey; }
.foo:where(:state(loading), :--loading, [state-loading]) { background: yellow; }
.foo:where(:state(loaded), :--loaded, [state-loaded]) { background: green; }
.foo:where(:state(error), :--error, [state-error]) { background: red; }
</style>
</code>
</pre>
</details>
<p>
Here are some details for what each of these states <em>mean</em>:
</p>
<ul>
<li>
<p>
<code>waiting</code> is the state used when the element is in the
DOM, but either does not have a <code>src=</code> or has
<code>loading=lazy</code> or <code>loading=none</code> and hasn't
yet begun to load. Once an element has left the <code>waiting</code>
state it'll never go back to it.
</p>
</li>
<li>
<p>
<code>loading</code> is the state used when the element is in making
a request, but the request hasn't yet completed. An individual
element can enter and exit this state multiple times per session.
</p>
</li>
<li>
<p>
<code>streaming</code> is the state used when the request was an
<code>text/event-stream</code> type, and the connection has been
opened. In this state events can stream in, and the
<code>loaded</code> state is removed. When the connection closes it
will transition to a <code>loaded</code> or <code>error</code>
state.
</p>
</li>
<li>
<p>
<code>loaded</code> is the state used when the element has
successfully completed and closed the request and has inserted the
content into the page, and has no more work to do for now. If the
<code>src=</code> changes, it might move back to the
<code>loading</code> state.
</p>
</li>
<li>
<p>
<code>error</code> is the state used when the element has completed
a request, but the request failed somehow. Unless in streaming mode,
the element won't have inserted any content into the page. If the
<code>src=</code> or <code>accept=</code> attributes change, it
might move back to the <code>loading</code> state.
</p>
</li>
</ul>
<h3 id="events">Events</h3>
<p>
There are a wealth of events that are fired for each stage of the
element's lifecycle. Just like <code><img></code> and
<code><iframe></code> elements, <code><i-html></code> elements
dispatch <code>loadstart</code>, <code>load</code>,
<code>loadend</code>, and <code>error</code> events to announce which
stage of the loading process they're in. They also dispatch
<code>beforeinsert</code>, and <code>inserted</code> events.
</p>
<ul>
<li>
<p>
<code>loadstart</code> is dispatched right before a request is
started. This event also has a <code>.request</code> property that
is the <code>Request</code> object that will be given to
<code>fetch()</code>. You can re-assign <code>.request</code> or
mutate some of its properties, and whatever changes you make to it
will propagate to the <code>fetch()</code> call, so the
<code>loadstart</code> event is really useful if you want to
customise requests beyond the default capabilities, for example
adding new headers. You can call <code>.preventDefault()</code> on
this event to stop loading happening altogether, and no subsequent
events will fire unless the request lifecycle is restarted (for
example by changing <code>src=</code>).
</p>
</li>
<li>
<p>
<code>load</code> is dispatched as soon as the request has completed
successfully. When streaming, this will be dispatched upon a
successful (non error) close of the <code>EventSource</code>. This
event does not come with any additional properties. This event isn't
fired if the network request had an error.
</p>
</li>
<li>
<p>
<code>error</code> is dispatched if the network request failed for
some reason, or if it was unable to be created for example due to
bad Request data. This can happen when streaming if the connection
errors, even after events have been sent. This event does not come
with any additional properties.
</p>
</li>
<li>
<p>
<code>loadend</code> is dispatched at the end of a request,
regardless of the end state of the request. In other words this will
always come directly after a <code>load</code> or <code>error</code>
event. This event does not come with any additional properties.
</p>
</li>
<li>
<p>
<code>beforeinsert</code> is dispatched right <em>before</em>the
contents are about to be inserted into the page. In streaming mode
this event could be fired many times. This comes with a
<code>.content</code> property which is an array of all the child
<code>Node</code>s about to be inserted into the element. If you
re-assign or otherwise mutate this array, then that is what will be
inserted. This is useful for doing extra sanitization or simply
removing elements with additional scripting. If you want to do
something even more radical, you can call
<code>.preventDefault()</code> and it will <em>not</em>
insert the contents, leaving it up to you what to do next. Other
events will continue to fire, and if in streaming mode, you may get
new data coming in.
</p>
</li>
<li>
<p>
<code>inserted</code> is dispatched right <em>after</em> the
contents have been inserted into the page, provided that
<code>beforeinsert</code> was not cancelled. In streaming mode this
event could be fired many times. This comes with a
<code>.content</code> property which is an array of all the child
<code>Node</code>s that were inserted - which may be different to
the elements <code>.childNodes</code>. This event is not
preventable, as the action has already happened.
</p>
</li>
</ul>
<h2 id="faq">Questions you might have</h2>
<h3 id="alternatives">What about using <alternative>?</h3>
<p>
There are many elements like this, but none that are <em>quite</em> like
this. I think this is a culmination of the best features of the other
elements.
</p>
<h3 id="more-alternatives">What about using htmx / htmz?</h3>
<p>
<a href="https://htmx.org/">htmx</a> and
<a href="https://leanrada.com/htmz">htmz</a> came as small inspiration
for this library. htmx is a great project which demonstrates the power
of leveraging HTML, and htmz is a great lightweight alternative that
leans into the web platform even futher, but it also lacks some real
niceties that you'd want from a component like this. This is why
<code><i-html></code> exists - to take the concepts of htmz and
expand them into a fully-fledged element, adding the missing features.
If you want a fully featured and more popular library, try htmx.
If you're after a really tiny codebase and leveraging as much of the
web platform as possible, htmz looks to be a great choice. If you're
after something a little bit in-between, I think <code><i-html></code>
is the best next step.
</p>
<h3 id="include-fragment">Why did you not extend include-fragment?</h3>
<p>
The
<a href="https://github.com/github/include-fragment-element"
>include-fragment-element</a
>
is very similar to this, and I'm the current maintainer of both, so it
is within my power (and hubris) to make changes to that element to make
it more like this element. However, I think they are spiritually
different elements. This element definitely builds upon the success of
<code><include-fragment></code>, but it also changes some design
decisions that aren't worth changing in
<code><include-fragment></code>, given its large user base and the
amount of churn it would take to make those changes. In that regard you
might consider this element a "rewrite" or a "major version bump" of
<code><include-fragment</code>, but I think both have a valid use
case and certainly both can co-exist, maybe even on the same website.
</p>
<h3 id="include-fragment-differences">
What are the differences between this and include-fragment then?
</h3>
<p>
Aside from the obvious difference being the name,
<code><include-fragment></code> has a smaller featureset, for example
it doesn't support streaming mode, it doesn't support custom CSS states,
it doesn't support preventing <code>loadstart</code> events. Those
things could be added, but then it also has some big differences that
are design decisions, and would be breaking changes.
<code><include-fragment></code> replaces <em>itself</em> on the page,
so a fully loaded fragment no longer exists on the page and the loaded
HTML stands in its place. This is different to
<code><i-html></code> which remains in the DOM, and can re-fetch
contents again and again. This design change gives the two elements very
different use cases, for example <code><i-html></code> respects link
and form <code>target=</code> attributes which would seem pointless to
do in <code><include-fragment></code> with this design choice in
mind.
</p>
</main>
</body>
</html>
================================================
FILE: package.json
================================================
{
"name": "i-html-element",
"version": "0.6.0",
"description": "A drop-in tag that allows for dynamically importing html, inline. It's a bit like an <iframe>, except the html gets adopted into the page.",
"main": "i-html.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"prepack": "npx esbuild --target=es2020 --minify --bundle i-html.js > i-html.min.js",
"prepublishOnly": "npm run prepack"
},
"files": [
"*.js"
],
"author": "Keith Cirkel <https://keithcirkel.co.uk>",
"license": "MIT"
}
gitextract_zvnutdbd/ ├── .github/ │ └── workflows/ │ ├── publish.yml │ └── static.yml ├── .gitignore ├── README.md ├── example-responses/ │ ├── ajax-form.html │ ├── dsd.html │ ├── empty.html │ ├── form-delete.html │ ├── form-save.html │ ├── hello.html │ ├── how-are-you.html │ ├── lazy.html │ ├── prepend-list.html │ ├── refresh-tock.html │ ├── refresh.html │ ├── sanitization.html │ ├── theme-gray.html │ ├── theme-pink.html │ ├── theme-yellow.html │ └── two-paragraphs.html ├── i-html.js ├── index.html └── package.json
SYMBOL INDEX (39 symbols across 1 files)
FILE: i-html.js
class StateSet (line 2) | class StateSet extends Set {
method constructor (line 5) | constructor(el, existing) {
method add (line 10) | add(state) {
method delete (line 23) | delete(state) {
method has (line 33) | has(state) {
method clear (line 36) | clear() {
class RequestEvent (line 50) | class RequestEvent extends Event {
method constructor (line 52) | constructor(request) {
class InsertEvent (line 58) | class InsertEvent extends Event {
method constructor (line 60) | constructor(name, content, init) {
function handleLinkTargets (line 66) | function handleLinkTargets(event) {
class IHTMLElement (line 84) | class IHTMLElement extends HTMLElement {
method src (line 87) | get src() {
method src (line 91) | set src(val) {
method credentials (line 95) | get credentials(){
method credentials (line 101) | set credentials(value) {
method #defaultTarget (line 105) | get #defaultTarget() {
method target (line 110) | get target() {
method target (line 120) | set target(value) {
method allow (line 125) | get allow() {
method allow (line 129) | set allow(value) {
method insert (line 135) | get insert() {
method insert (line 142) | set insert(value) {
method loading (line 146) | get loading() {
method loading (line 152) | set loading(value) {
method accept (line 156) | get accept() {
method accept (line 166) | set accept(val) {
method constructor (line 195) | constructor() {
method attributeChangedCallback (line 208) | attributeChangedCallback(name, old, value) {
method connectedCallback (line 226) | connectedCallback() {
method handleEvent (line 236) | handleEvent(event) {
method disconnectedCallback (line 264) | disconnectedCallback() {
method #observe (line 268) | #observe() {
method #setupRefresh (line 273) | #setupRefresh(refresh) {
method #load (line 283) | async #load(src, options) {
method #stream (line 339) | async #stream(request) {
method #loadOnce (line 363) | async #loadOnce(request) {
method #parseAndInject (line 394) | #parseAndInject(responseText, mime) {
method #sanitize (line 432) | #sanitize(doc) {
Condensed preview — 23 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (66K chars).
[
{
"path": ".github/workflows/publish.yml",
"chars": 669,
"preview": "name: Publish\n\non:\n release:\n types: [created]\n\njobs:\n publish-npm:\n name: Publish to npm\n runs-on: ubuntu-la"
},
{
"path": ".github/workflows/static.yml",
"chars": 1250,
"preview": "# Simple workflow for deploying static content to GitHub Pages\nname: Deploy static content to Pages\n\non:\n # Runs on pus"
},
{
"path": ".gitignore",
"chars": 27,
"preview": "node_modules\ni-html.min.js\n"
},
{
"path": "README.md",
"chars": 275,
"preview": "## i-html\n\n[i-html](https://github.com/keithamus/i-html) is a drop in tag that allows for dynamically _importing_ html,\n"
},
{
"path": "example-responses/ajax-form.html",
"chars": 443,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <form\n action=\"example-responses/ajax-form.html\"\n method=\"get\"\n target"
},
{
"path": "example-responses/dsd.html",
"chars": 446,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <div>\n <template shadowrootmode=\"open\">\n <p><slot></slot></p>\n\n <s"
},
{
"path": "example-responses/empty.html",
"chars": 67,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <span></span>\n </body>\n</html>\n"
},
{
"path": "example-responses/form-delete.html",
"chars": 101,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>Whatever was saved has now been deleted.</p>\n </body>\n</html>\n"
},
{
"path": "example-responses/form-save.html",
"chars": 137,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>Your form would have been saved if I was't too cheap to spring for a server.</p>\n "
},
{
"path": "example-responses/hello.html",
"chars": 73,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>Hello world!</p>\n </body>\n</html>\n"
},
{
"path": "example-responses/how-are-you.html",
"chars": 73,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>How are you?</p>\n </body>\n</html>\n"
},
{
"path": "example-responses/lazy.html",
"chars": 152,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>This loaded in very lazily... but you might not have seen (try looking in network "
},
{
"path": "example-responses/prepend-list.html",
"chars": 91,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <ul>\n <li>Butter</li>\n </ul>\n </body>\n</html>\n\n"
},
{
"path": "example-responses/refresh-tock.html",
"chars": 146,
"preview": "<!DOCTYPE html>\n<html>\n <head>\n <meta http-equiv=\"refresh\" content=\"1;url=refresh.html\">\n </head>\n\t<body>\n <p>To"
},
{
"path": "example-responses/refresh.html",
"chars": 151,
"preview": "<!DOCTYPE html>\n<html>\n <head>\n <meta http-equiv=\"refresh\" content=\"1;url=refresh-tock.html\">\n </head>\n\t<body>\n "
},
{
"path": "example-responses/sanitization.html",
"chars": 328,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>This response contained an <code><i-html></code> element, but it was sanitized "
},
{
"path": "example-responses/theme-gray.html",
"chars": 311,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <style>\n :root {\n --background: #f6f8fa !important;\n --color: #1f2"
},
{
"path": "example-responses/theme-pink.html",
"chars": 311,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <style>\n :root {\n --background: #fff0f6 !important;\n --color: #a61"
},
{
"path": "example-responses/theme-yellow.html",
"chars": 311,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <style>\n :root {\n --background: #fff9db !important;\n --color: #d94"
},
{
"path": "example-responses/two-paragraphs.html",
"chars": 193,
"preview": "<!DOCTYPE html>\n<html>\n\t<body>\n <p>\n This was the first paragraph from the response.\n </p>\n <p>\n This"
},
{
"path": "i-html.js",
"chars": 14571,
"preview": "// A small polyfill for CSSStateSet\nclass StateSet extends Set {\n #el = null\n #existing = null\n constructor(el, exist"
},
{
"path": "index.html",
"chars": 41562,
"preview": "<!doctype html>\n<html lang=\"en\">\n <head>\n <title>i-html, an inline-html import element</title>\n <meta name=\"viewp"
},
{
"path": "package.json",
"chars": 549,
"preview": "{\n \"name\": \"i-html-element\",\n \"version\": \"0.6.0\",\n \"description\": \"A drop-in tag that allows for dynamically importin"
}
]
About this extraction
This page contains the full source code of the keithamus/i-html GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 23 files (60.8 KB), approximately 16.5k tokens, and a symbol index with 39 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.