include-content
One-stop shop for rendering a view when & where you need it — lazy-loading/unloading, conditional rendering, portalling… no app JS required.
Features
- Zero JS Sophisticated UX from a simple HTML-only API, as with all NucleusKit elements.
- Lazy (un)load Lazy load and lazy unload your views
- Eager / idle Prioritize critical content; defer the rest
- Prefetch Warm templates so they're ready on activate
- Shared / remote templates Point at a DOM
<template>or URL - Choose the host Portal into light DOM, shadow, author iframe, or any selector
- Keep state Reuse the same tree across toggles
- Animatable Built-in fade, or bring your own with
.instant
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/include-content@0.1.4/dist/index.umd.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@excom/include-content@0.1.4/dist/index.css">npm install @excom/include-content<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/include-content"></script>
<link rel="stylesheet" href="/node_modules/@excom/include-content">import "@excom/include-content";@import "@excom/include-content/index.css";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
Usage
Put a <template> inside (or set template-ref) and pick when it should appear. For conditional rendering, use Quark or JS to toggle is-active.
<include-content lazy-load template-ref="/path/to/view.html"></include-content><include-content lazy-load template-ref="/path/to/view.html"></include-content>API Reference
Attributes
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
include-content
Attributes (18)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
bypass-cache
Skip the in-memory response cache (URL renderable-element
template-ref only).
bypassCache
boolean
falsehost-ref
Where rendered children land. Unset = this element's light DOM. renderable-element
shadow attaches an open shadow root. iframe paints into a child <iframe data-render-host> body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector.
hostRef
string
"shadow" | "iframe" | <CSS Selector>nullidle-load
Activate after first paint, when the browser is idle. Useful for below-the-fold / secondary views that should not compete with critical content.
idleLoad
boolean
falselazy-load
Activate when this element is on screen. Pair with
lazy-unload for lazy load and lazy unload of views.
lazyLoad
boolean
falselazy-unload
Deactivate (unrender) when no longer on screen. Use with
lazy-load to free DOM for off-screen views.
lazyUnload
boolean
falseobserver-delay
Minimum time visible before activating (ms). Ignored where unsupported. Useful for ensuring lazy load is not triggered when a programmatic smooth scroll zips the user right past the element.
observerDelay
number
0observer-root
Scroll container for lazy load / unload. Defaults to the viewport.
observerRoot
string
<CSS Selector>nullobserver-root-margin
How far outside the root counts as "visible". Expand (e.g.
500px) to lazy-load a view before it enters the viewport so users never see an empty slot; shrink (default -1px) so edge-flush elements wait until they truly enter.
observerRootMargin
string
<length> | <percentage>"-1px -1px -1px -1px"observer-threshold
Fraction of the element that must be visible (
0–1) before activating.
observerThreshold
number
nullpersist-content
Reuse the same live nodes across unrender / render (held on renderable-element
_persistedTree) so form values, scroll position, and subtree state survive toggles.
persistContent
boolean
falsepre-fetch
When to fetch the template, independent of when it renders. renderable-element
"" aliases eager. idle never runs in a prerender.
preFetch
string
"" | "eager" | "idle" | "lazy""lazy"ready-on
Event name that marks rendered children "ready". Until it fires, renderable-element
delaying-ready is set so CSS can hide the host for a coordinated paint / view transition. Prerendered content kept at hydration is ready at once, never hidden.
readyOn
string
<Event Name>nulltemplate-ref
Source renderable-element
<template> — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use :scope to relatively select elements: e.g. main:has(:scope) > template
templateRef
string
<CSS Selector> | <URL>":scope > template"is-active
Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc.
renderable-element
isActive
boolean
falsedelaying-ready
Between renderable-element
render and the matching ready-on event (or a failed load). Hook with CSS for coordinated paints / view transitions.
delayingReady
boolean
falsedid-load
Template resolved at least once. Stays set across renderable-element
is-active toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when template-ref changes or --reload forces a fresh resolve.
didLoad
boolean
falseis-error
Latest template fetch rejected (excluding abort). Fires with the renderable-element
error event.
isError
boolean
falseis-loading
Template fetch in flight.
renderable-element
isLoading
boolean
falseProvision (0)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events (7)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
include-content-aborted
Dispatched when an in-flight load / ready wait is canceled because renderable-element
is-active was unset (via startTeardown).
Type
RenderableAbortedEvent
include-content-did-render
Dispatched after the template content has actually been placed into the host.
renderable-element
Type
RenderableDidRenderEvent
include-content-did-unrender
Dispatched after rendered children have been removed from the host.
renderable-element
Type
RenderableDidUnrenderEvent
include-content-error
Dispatched when the template promise rejects with anything other than an renderable-element
AbortError.
Type
RenderableErrorEvent
include-content-render
Cancelable. Dispatched when the element becomes active and is about to place template content into the host. renderable-element
event.detail is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding ready-on event fires (or immediately if ready-on is unset). The promise rejects if the template fails to load, host-ref resolves to no host (nor an author iframe still loading), or the element is torn down mid-flight (startTeardown while loading / delaying-ready). Call preventDefault() to defer rendering and invoke event.detail() later.
Type
RenderableRenderEvent
event.detail() to load (if needed) and render the template into the host.include-content-unrender
Cancelable. Dispatched when the element becomes inactive and content is already painted. renderable-element
event.detail is a thunk that removes the rendered children. Call preventDefault() to defer the removal. Not fired when teardown cancels an in-flight load — that path emits aborted instead.
Type
RenderableUnrenderEvent
event.detail() to remove rendered children from the host.command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
--reloadRecognized Elements (2)
Child or descendant elements are recognized by include-content and relevant to its functionality.
Required when renderable-element
host-ref="iframe". Content paints into iframe.contentDocument.body. Provide your own iframe (e.g. with srcdoc); the element will not create one.
Optional immediate renderable-element
<template> child used when template-ref is the default ":scope > template". Not required when template-ref points at a selector or URL elsewhere.
Styles (9)
.instant
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
--include-content-transition-duration<time>0.15s--include-content-transition-ease*ease-in@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
:--include-contentinclude-content, .tag-include-content:--include-content--did-load[did-load], [data-did-load]:--include-content--host-shadow[host-ref="shadow"], [data-host-ref="shadow"]:--include-content--is-active[is-active], [aria-current]:--include-content--lazy-load[lazy-load], [data-lazy-load]:--include-content--lazy-unload[lazy-unload], [data-lazy-unload]Release notes (1)
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Examples
Template include
Break your app into smaller views. Point template-ref at a <template> or a URL with is-active to render it immediately. This demo does both. A <script> inside a URL template does not run; stylesheets, <style> and <quark-sheet> do.
Lazy Load & Unload
lazy-load waits until on screen; lazy-unload removes it when it leaves. Give the host a real min-height so the trigger isn't ambiguous. Tune with observer-root, observer-root-margin, observer-threshold, and observer-delay — e.g. expand the margin to pre-render before the user scrolls to it. If remote template, pair with pre-fetch="idle" to warm the cache early.
Portal elsewhere
By default content lands in the element's light DOM. Set host-ref to
shadow, iframe (with a child <iframe data-render-host>), or any CSS
selector to render somewhere else. The iframe host only moves nodes: custom
elements inside it upgrade only if that document loads their definitions.
Keep tree state
Toggling is-active off leaves did-load set (warm re-resolve; URL
refs hit the shared fetch cache). persist-content goes further and
reuses the same live nodes so implicit state (form values, open details,
etc.) survives toggles.