onEach

Reactively iterates over the items of an observable array, object, Map, or Set, optionally rendering content for each item.

Automatically updates when items are added, removed, or modified.

Param

target

The observable array, object, Map, or Set to iterate over. Values that are undefined are skipped.

Param

render

A function called for each item. It receives the item’s (observable) value and its index/key. For Sets, only the value is provided. Any DOM elements created within this function will be associated with the item, placed at the right spot in the DOM, and cleaned up when redrawing/removing the item.

Param

makeKey

An optional function to generate a sort key for each item. This controls the order in which items are rendered in the DOM. If omitted, arrays use index order, Sets use the item value itself, and objects/Maps use their natural key order. The returned key can be a number, string, or an array of numbers/strings for composite sorting. Use invertString on string keys for descending order. Returning null or undefined from makeKey will prevent the item from being rendered.

makeKey runs in a reactive scope of its own: when observable data it reads changes the resulting key, the item’s DOM nodes are moved to their new position without being redrawn (so state like <input> values survives, and — in browsers supporting the moveBefore API — focus, text selection and CSS animations do too). Changes that switch the key between null-ish and an actual value show/hide the item, and therefore do cause a (re)render. makeKey must not create DOM nodes.

Examples

Iterating an array

const $items = A.proxy(['apple', 'banana', 'cherry']);

// Basic iteration
A.onEach($items, (item, index) => A(`li#${item} (#${index})`));

// Add a new item - the list updates automatically
setTimeout(() => $items.push('durian'), 2000);
// Same for updates and deletes
setTimeout(() => $items[1] = 'berry', 4000);
setTimeout(() => delete $items[2], 6000);

Iterating an array with custom ordering

const $users = A.proxy([
    { id: 3, group: 1, name: 'Charlie' },
    { id: 1, group: 1, name: 'Alice' },
    { id: 2, group: 2, name: 'Bob' },
]);

// Sort by name alphabetically
A.onEach($users, ($user) => {
    A(`p#${$user.name} (id=${$user.id})`);
}, ($user) => [$user.group, $user.name]); // Sort by group, and within each group sort by name

Iterating an object

const $config = A.proxy({ theme: 'dark', fontSize: 14, showTips: true });

// Display configuration options
A('dl', () => {
    A.onEach($config, (value, key) => {
        if (key === 'showTips') return; // Don't render this one
        A('dt#'+key);
        A('dd#'+value);
    });
});

// Change a value - the display updates automatically
setTimeout(() => $config.fontSize = 16, 2000);

Iterating a Set

const $tags = A.proxy(new Set(['ui', 'fast', 'tiny']));

A('ul', () => {
    A.onEach($tags, (tag) => { // Defaults to alphabetically ordering by tag
        A(`li#${tag}`);
    });
});

setTimeout(() => $tags.add('reactive'), 2000);

See

invertString To easily create keys for reverse sorting.

Call Signature

onEach<K, T>(target, render, makeKey?): void

Defined in: aberdeen.ts:1249

Type Parameters

K

K

T

T

Parameters

target

Map<K, T>

render

(value, key) => void

makeKey?

(value, key) => SortKeyType

Returns

void

Call Signature

onEach<T>(target, render, makeKey?): void

Defined in: aberdeen.ts:1254

Type Parameters

T

T

Parameters

target

Set<T>

render

(value) => void

makeKey?

(value) => SortKeyType

Returns

void

Call Signature

onEach<T>(target, render, makeKey?): void

Defined in: aberdeen.ts:1259

Type Parameters

T

T

Parameters

target

readonly T[]

render

(value, index) => void

makeKey?

(value, index) => SortKeyType

Returns

void

Call Signature

onEach<K, T>(target, render, makeKey?): void

Defined in: aberdeen.ts:1264

Type Parameters

K

K extends string | number | symbol

T

T

Parameters

target

Record<K, undefined | T>

render

(value, index) => void

makeKey?

(value, index) => SortKeyType

Returns

void