@magnet/list

Data-keyed identity-stable list rendering for Magnet.

list renders item arrays as nodes created once per item and reused across changes: swaps become moves, removals dispose only the removed nodes, and appends create only the new ones. The cache lives in the package, so apps never handle DOM nodes directly.

Install

JSR

deno add jsr:@magnet/list

npm via JSR

npx jsr add @magnet/list

npm

npm install @magnet-js/list

API

list(signal)

Creates a List function bound to signal primitives. Accepts any object with computed and isSignal — a Magnet context satisfies the interface directly.

List

list(m)(items, render, key?)

• items — the source array, or a signal of it. Plain arrays compute eagerly with no reactive machinery; signal arrays return a Computed that re-evaluates on change, so components accept either shape without forking.
• render(item, index) — creates the node for an item, called once per item.
• key?(item) — optional key extractor; defaults to object identity. Use it with primitive keys (for example row.id) or when items are recreated with the same logical identity (immutable updates).

Returns the identity-stable nodes, renderable as children. On every change, the same items yield the same nodes, so Magnet's keyed list update moves and reuses them: swaps become moves, removals dispose only the removed nodes, and appends create only the new ones.

import { list } from "@magnet/list";

const items = m.state([{ id: 1, label: "a" }, { id: 2, label: "b" }]);

m.html.tbody(
  list(m)(
    items,
    (item) => m.html.tr([m.html.td([item.label])]),
    (item) => item.id,
  ),
);

Types

• List — the bound function's interface (overloaded for plain and signal arrays).
• Render<T, N> — the item render function's type.
• KeyOf<T> — the key extractor's type.

License

MIT © 2026 Fernando G. Vilar.