Atomico Rendering

The function underlying JSX transformation.

import { createElement, h } from "atomico";

// These are equivalent:
const vnode1 = createElement("div", { class: "card" }, "Hello");
const vnode2 = h("div", { class: "card" }, "Hello");
const vnode3 = <div class="card">Hello</div>;  // JSX

VNode Structure

{
    type: "div" | Constructor | Node,
    props: { ... },
    key: any
}

Virtual DOM Reconciliation

Keyed Lists

When children have key props, Atomico uses keyed reconciliation:

{items.map((item) => (
    <li key={item.id}>{item.name}</li>
))}

• Keyed nodes are tracked in a Map<key, ChildNode>
• Reordered nodes use moveBefore (if available) to preserve internal state (focus, scroll position, etc.)
• Orphaned keyed nodes are collected and removed after reconciliation

Non-Keyed Lists

Without keys, Atomico uses positional matching and replaces nodes in-place.

moveBefore API

Atomico detects browser support for moveBefore and uses it for keyed list reordering. This preserves:

• Input focus state
• Scroll positions
• CSS animations
• <video>/<audio> playback state

Fragment

Groups children without adding a DOM wrapper:

import { Fragment } from "atomico";

<Fragment>
    <p>First</p>
    <p>Second</p>
</Fragment>

Mark — Internal Fragment Boundary

Mark extends Text — used internally to delimit fragment boundaries in the DOM. The renderChildren algorithm uses Mark instances as sentinels.

Note: Mark nodes are filtered out by useSlot and useNodes hooks automatically. You should never need to create or interact with them directly.

render — Mount VNodes to DOM

The imperative render function for mounting virtual DOM trees:

import { render, createElement } from "atomico";

render(
    createElement("host", { children: "Hello" }),
    document.getElementById("app")
);

Component Instance Properties

Every Atomico element instance has these special properties:

Waiting for Render Completion

const el = new MyComponent();
document.body.appendChild(el);
await el.updated;
// DOM is now fully rendered

Utilities

createRef

Creates a ref object { current: T }:

import { createRef } from "atomico";

const ref = createRef<HTMLElement>();
ref.current;  // HTMLElement | undefined

className (from atomico/utils)

Concatenates class names, filtering falsy values:

import { className } from "atomico/utils";

className("base", isActive && "active", isLarge && "large");
// "base active" (if isActive is true, isLarge is false)

delegateValidity (from atomico/utils)

Extracts validity state from a native input for use with useFormValidity:

import { delegateValidity } from "atomico/utils";

const result = delegateValidity(inputElement);
// { valid, message, valueMissing, tooShort, ... }

Property Assignment Logic

When setting properties on DOM nodes, Atomico follows this priority:

1. shadowDom, staticNode, cloneNode, children, key: Internal props, not applied to the DOM
2. on* handlers: Registered as event listeners with event delegation
3. ref: Applied as .current = node or called as function
4. style: Applied as object (per-property) or string (cssText)
5. assignNode on <slot>: Calls slot.assign(node) in a task queue
6. $-prefixed: Always set as attributes (forces attribute mode)
7. Properties in element prototype (and not in PROPS_AS_ATTRS): Set as properties
8. Everything else: Set as attributes

Special Attributes (Always Set as Attributes)

list, type, size, form, width, height, src, href, slot

Checked Properties (Read from DOM)

checked, value, selected — values are read from the DOM node before comparison to detect external mutations.