Reactive Lists: `$for( )`

The $for function is a high-performance list renderer. It maps an array (or a Signal containing an array) to DOM nodes. Unlike a simple .map(), $for is keyed, meaning it only updates, moves, or deletes the specific items that changed.

Function Signature

$for(
  source: Signal<any[]> | Function | any[], 
  render: (item: any, index: number) => HTMLElement, 
  keyFn?: (item: any, index: number) => string | number
): HTMLElement

Parameter	Type	Required	Description
`source`	`Signal`	Yes	The reactive array to iterate over.
`render`	`Function`	Yes	A function that returns a component or Node for each item.
`keyFn`	`Function`	No	A function to extract a unique ID. If omitted, it defaults to the `index`.

Returns: A div element with display: contents containing the live list.

Usage Patterns

1. Basic Keyed List (Recommended)

Always use a unique property (like an id) as a key to ensure SigPro doesn't recreate nodes unnecessarily when reordering or filtering.

const users = $([
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob" }
]);

Ul({ class: "list" }, [
  $for(users, 
    (user) => Li({ class: "p-2" }, user.name),
    (user) => user.id // Stable and unique key
  )
]);

2. Simplified Usage (Automatic Key)

If you omit the third parameter, $for will automatically use the array index as the key. This is ideal for simple lists that don't change order frequently.

const tags = $(["Tech", "JS", "Web"]);

// No need to pass keyFn if the index is sufficient
Div({ class: "flex gap-1" }, [
  $for(tags, (tag) => Badge(tag)) 
]);

How it Works (The Reconciliation)

When the source signal changes, $for performs the following steps:

Key Diffing: It compares the new keys with the previous ones stored in an internal Map.
Node Reuse: If a key already exists, the DOM node is reused and moved to its new position. No new elements are created.
Physical Cleanup: If a key disappears from the list, SigPro calls .destroy() to stop reactivity and physically removes the node from the DOM to prevent memory leaks.

Performance Tips

Stable Keys: Never use Math.random() as a key. This will force SigPro to destroy and recreate the entire list on every update, killing performance.
State Preservation: If your list items have internal state (like an input with text), $for ensures that state is preserved even if the list is reordered, as long as the key (id) remains the same.

Summary Comparison

Feature	Standard `Array.map`	SigPro `$for`
Re-render	Re-renders everything	Only updates changes
DOM Nodes	Re-created every time	Reused via Keys
Memory	Potential leaks	Automatic Cleanup
State	Lost on re-render	Preserved per item
Ease of Use	Manual logic required	Optional (fallback to index)

3.0 KiB Raw Blame History

Reactive Lists: $for( )