renderable-element

Composition base for Neutron elements that defer rendering a <template> until the right moment. It owns the load + render lifecycle so subclasses only decide when to flip is-active. Used by <include-content>, <spa-route>, and any custom element you compose yourself.

The demos below use <include-content> (the simplest concrete subclass) to exercise behavior that comes straight from this mixin.

Features

• Template resolution via template-ref in-document selectors or remote URLs
• Prefetch strategies lazy (default), eager, or idle
• Configurable render host light DOM, shadow, author iframe, or any selector
• Cancelable render / unrender parents can wrap updates in view transitions
• Persistable content keep live subtree state across unrender / render cycles
• Ready coordination ready-on + delaying-ready for paint-synced reveals

Installation

<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/renderable-element@0.3.0/dist/index.umd.min.js"></script>

npm install @excom/renderable-element

import { /* … */ } from "@excom/renderable-element";

Usage

Compose RenderableElement into a Neutron class and toggle isActive from whatever signal makes sense — a media query, a websocket message, an experiment flag, etc. Everything else (template fetch, caching, host resolution, lifecycle events) is inherited.

import { Neutron } from "@excom/neutron";
import { RenderableElement } from "@excom/renderable-element";
​
export const MediaGated = Neutron.compose([
  RenderableElement,
  Neutron({
    tag: "media-gated",
    props: {
      mediaQuery: String,
    },
  }),
])
  .onPropChanged("mediaQuery", (el, prev) => {
    prev.mediaQuery && el._mql?.removeEventListener("change", el._sync);
    if (!el.mediaQuery) return { isActive: false };
    el._mql = window.matchMedia(el.mediaQuery);
    el._sync = () => (el.isActive = el._mql.matches);
    el._mql.addEventListener("change", el._sync);
    el._sync();
  });
​
MediaGated.define();

<media-gated media-query="(min-width: 900px)">
  <template>
    <wide-screen-only></wide-screen-only>
  </template>
</media-gated>

Event names are prefixed with the concrete tag (shown as {tag}-… in the API). For <include-content> that means include-content-render, etc.

API Reference

Examples

Choosing a render host

Unset host-ref renders into the element's light DOM. "shadow" attaches an open shadow root for style isolation:

"iframe" paints into a child <iframe data-render-host> you provide — sandbox styles / scripts / document context. Only nodes move: custom elements upgrade there only if the iframe document loads their definitions:

Any other value is a CSS selector — the template lands in whatever element it resolves to:

On a prerendered page the light DOM and a selector host keep their prerendered content; shadow and iframe hosts are not prerendered and render in the browser.

Hooking render with view transitions

render and unrender are cancelable; event.detail is the update thunk. A parent can preventDefault() and run the mutation inside document.startViewTransition() — the same pattern <spa-manager> uses to batch sibling routes.

The thunk's returned Promise resolves when the view is ready (immediately, or when ready-on fires). If is-active is unset while still loading / delaying-ready, teardown rejects that Promise and emits aborted instead of unrender.

Pair with ready-on so delaying-ready stays set until your transition has committed:

<media-gated ready-on="my-app-paint" media-query="(min-width: 900px)">
  <template>...</template>
</media-gated>

media-gated[delaying-ready] {
  display: none;
}

Persisting content across cycles

Once a template resolves, did-load stays set so consumers know later toggles are warm — URL template-refs reuse the shared fetch cache in kit-utils. Without persist-content (the default), each activation re-resolves and imports a fresh clone — subtree state is lost on unrender. With it, the same live nodes are held across toggles:

On a prerendered page the nodes it holds are the prerendered ones.

Loading strategies

pre-fetch controls when the template is fetched, separately from when it is rendered:

<!-- default: fetch on first activation -->
<my-el></my-el>
​
<!-- pre-warm immediately on attribute set -->
<my-el pre-fetch="eager"></my-el>
​
<!-- backfill on idle -->
<my-el pre-fetch="idle" template-ref="/fragments/hero.html"></my-el>

Pair with bypass-cache for revalidation when the element activates multiple times. Invoke the --reload command to force a refresh.

pre-fetch="idle" never runs in a prerender: the template is fetched in the browser.