Imperative Components
Normative guide to creating custom elements from Coralite client code, including scan boundaries, dependency tracking, runtime loaders, upgrade timing, ownership, styling, testing, and troubleshooting.
This page is the canonical reference for creating custom elements from Coralite client-side code. It covers where creation should live, how Coralite tracks dependencies, how loading and upgrades work, and what changes between development, testing, and production.
This page owns imperative-component behavior. The JavaScript guide, plugin guide, plugin reference, and E2E guide summarize it. llms-full.txt mirrors it as a standalone LLM reference. Update this page first when the contract changes.
Choosing a Creation Path
Prefer declarative markup. Use imperative creation only when the element cannot exist at build time, such as a component created in response to a user action or a plugin-provided DOM factory.
| Location | Scanned? | Recommended use |
|---|---|---|
| Declarative HTML | N/A | Default for static and SSR-rendered content. |
Component client() |
Yes | Local interactive DOM owned by one component. |
Page client() |
Yes | Page-level DOM that is not owned by a single component. |
Plugin client.context, client.init, client lifecycle hooks |
Yes | Shared cross-page DOM factories and plugin-owned UI. |
| Dynamically imported helper module | No | Pure formatting, mapping, and data shaping. Use public runtime helpers if DOM creation is unavoidable. |
Scan Boundary and Dependency Tracking
Coralite scans the source of component/page client() controllers and plugin client functions. The scanned APIs are document.createElement, innerHTML, outerHTML, and insertAdjacentHTML. Calls are rewritten to Coralite's on-demand component loaders.
Literal tags are preferred because the concrete tag can be recorded in page/component metadata and used for dependency tracking and cache invalidation:
const card = document.createElement('event-card')
Dynamic tag expressions are still rewritten and lazy-load at runtime, but the concrete component may not appear in build metadata. If the component is not otherwise declared on the page, prefer a literal tag or load it explicitly.
Dynamically imported helper modules are bundled by esbuild, but their bodies are not AST-scanned for custom-element creation. Moving document.createElement('event-card') into a helper module can therefore work in development or testing and fail in production. Keep helpers pure, pass a factory from scanned code, or use the public runtime helpers below.
Rewrite Contract
These transformations happen only in scanned client code:
| Authored call | Rewrite target | Notes |
|---|---|---|
document.createElement(tag) |
createCoraliteElement(tag) |
Literal custom-element tags are tracked. Built-in HTML tags are left native. |
element.innerHTML = html |
processHTML(html, instanceId) |
Loads custom elements found in the HTML and scopes refs when an instance is known. |
element.outerHTML = html |
processHTML(html, instanceId) |
Same processing as innerHTML. |
element.insertAdjacentHTML(position, html) |
processHTML(html, instanceId) |
The original insertion method still performs the DOM write. |
createCoraliteElement and processHTMLTarget are compiler helpers. They are implementation details of the rewrite, not supported user-facing APIs. Application and plugin code should use the public runtime APIs when it needs to create or load elements outside scanned code.
Public Runtime APIs
For unscanned helper modules, use the public methods on window.__coralite__.dom:
window.__coralite__.dom.createElement(tag, options?): creates an element and starts the on-demand component upgrade when the tag is registered.window.__coralite__.dom.loadComponent(tag): imports and defines the component module. It deduplicates concurrent loads for the same tag.window.__coralite__.dom.upgrade(root): upgrades the root and matching descendants, then waits forupdateCompleteon upgraded elements.window.__coralite__.dom.processHTML(html, instanceId?): processes an HTML string, loads discovered custom elements, and scopes refs when an instance ID is provided.
Loading is asynchronous. loadComponent() resolves after the component module is defined; component styles are injected as part of loading and may finish separately. Use customElements.whenDefined(tag) or the element's updateComplete when ordering matters.
Ownership and Refs
When a component context or lifecycle hook is available, Coralite uses its instanceId to scope refs inside injected HTML. If the instance cannot be determined statically, Coralite falls back to the insertion target's owning component. A new ref that is not declared in component state is not automatically added to refs().
See the DOM refs guide for the full ref ownership model, including nested components and slotted content.
Styling and Assets
Imperatively created components load their component CSS through the same manifest as declaratively created components. Because the element does not exist during SSR, its markup and styles may appear after the initial page paint; avoid relying on imperatively created elements for above-the-fold critical layout.
See the styling guide for scoped selectors, host styling, and CSS custom properties.
SSR, Hydration, and Lifecycle
Imperative creation is client-only. The element does not participate in SSR output or hydration payloads unless it is also rendered declaratively elsewhere. Recreating an element that is already present can cause duplicate content; make creation idempotent or guard it in the owning controller.
Imperatively created Coralite components follow the normal connected/disconnected lifecycle. Clean up listeners and external resources with the component's signal.
Testing Matrix
| Mode | DOM prototype patches | What it proves |
|---|---|---|
development |
Yes | Fast local iteration; missing dependency tracking can be masked. |
testing |
Yes | Deterministic E2E behavior; missing dependency tracking can still be masked. |
production |
No | Real deployment behavior. Use this to verify imperative component loading. |
Add at least one production-build E2E test when components are created imperatively or outside scanned code. See the E2E testing guide.
Troubleshooting
- Element exists but is empty: the component was not loaded or upgraded. Confirm the tag is tracked, or call
dom.loadComponent(tag)/dom.createElement(tag). - Works in development/testing but fails in production: creation likely lives in an unscanned helper module or another path that relied on DOM prototype patches. Move creation into scanned code or use the public runtime APIs.
- Styles are missing: the component may not have loaded at all, or its CSS link may still be in flight. Verify the component manifest entry and loading order.
refs()returns null: the ref may be dynamically injected without a matchingstate.ref_<name>, or ownership may point at a nested component. See the DOM refs guide.- Duplicate content: the controller may create the element more than once, or it may duplicate a declaratively rendered element. Make creation idempotent.