ElementList

Manages the ordered list of child nodes under an ElementNode. Accessed via node.children.

node.children          // ElementList
node.children.items    // NodeItem[]

Properties

Methods

insert(input, index?, updateDom?, silent?)

Creates a new child node and inserts it at the given index. Returns the new node.

// Append at end
const created = node.children.insert({ div: "Hello" })

// Insert at specific index
const created = node.children.insert({ div: "Hello" }, 2)

// Insert without touching DOM (DOM already updated externally)
const created = node.children.insert({ div: "Hello" }, 2, false)

Returns the created ElementNode or TextNode. Cast to ElementNode when you need methods like .remove():

const toastNode = node.parent!.children.insert(Toast) as ElementNode
setTimeout(() => toastNode.remove(), 3000)

remove(item, updateDom?, silent?)

Removes a specific node from the list.

node.children.remove(targetNode)

// Remove without touching DOM
node.children.remove(targetNode, false)

Triggers BeforeRemove hook if present — removal waits for done() to be called.

update(inputs, updateDom?, silent?)

Reconciles the child list against a new array of inputs. Reuses keyed nodes, inserts new ones, removes stale ones — in order.

node.children.update(newItemsArray)

// Sync logical list without touching DOM (DOM already updated externally)
node.children.update(newItemsArray, false)

Pass false for updateDom when an external library (e.g. SortableJS) has already updated the DOM — prevents double update.

move(fromIndex, toIndex, updateDom?, silent?)

Moves a node from one index to another within the list.

node.children.move(0, 2)

// Move logical position only — DOM already moved externally
node.children.move(oldIndex, newIndex, false)

swap(aIndex, bIndex, updateDom?, silent?)

Swaps two nodes at the given indices.

node.children.swap(0, 1)

clear(updateDom?, silent?)

Removes all children.

node.children.clear()

generateHTML()

Generates the HTML string for all child nodes. Used for Server-Side Rendering (SSR).

const html = node.children.generateHTML()

The updateDom flag

All mutating methods accept updateDom (default true). Pass false when the DOM has already been updated by an external source — prevents double mutation.

Common case: SortableJS drag-and-drop.

Sortable.create(el, {
    onEnd(evt) {
        // SortableJS already moved the DOM node — sync logical tree only
        node.children.move(evt.oldIndex!, evt.newIndex!, false)
    }
})

Common patterns

Insert and auto-remove (toast):

onClick: (_, node) => {
    const toastNode = node.parent!.children.insert(Toast) as ElementNode
    setTimeout(() => toastNode.remove(), 3000)
}

Reactive list (state-driven):

const items = toState<Item[]>([])

const List: DomphyElement<"ul"> = {
    ul: (listener) => items.get(listener).map(item => ({
        li: item.name,
        _key: item.id,
    }))
}

Imperative reorder:

node.children.move(from, to)
node.children.swap(a, b)