Lists & repeat

Efficient list rendering with repeat(), keyed(), and when().

import { html, repeat } from 'mates';

const items = [{ id: 1, text: 'Ship it' }];

// Key-based reconciliation — prefer for reorder/insert/remove
html`
  ${repeat(
    items,
    (i) => i.id,
    (i) => html`<li>${i.text}</li>`,
  )}
`;

Overview

You can render arrays of TemplateResults with .map() inside html. For lists that insert, remove, or reorder, use repeat(items, keyFn, templateFn) so existing DOM nodes move with their keys instead of being recreated.

repeat is re-exported from lit-html via mates. For thousands of rows, step up to virtualList from mates-virtual — see /docs/directives/virtual.

.map() vs repeat() vs virtualList

API	Best for	Notes
`items.map(…)`	Short / append-only	Simple. May recreate nodes on reorder.
`repeat(items, keyFn, tpl)`	Keyed lists	Moves existing nodes — better for mutable lists.
`virtualList(…)`	Huge lists	From mates-virtual — only visible rows in the DOM.

Rendering lists with repeat()

.map() works for simple lists, but repeat(items, keyFn, templateFn) is more efficient when items are added, removed, or reordered — it moves existing DOM nodes instead of recreating them.

import { html, atom, renderApp, repeat } from 'mates';

const App = () => {

const items = atom([

{ id: 1, text: 'Learn Mates', done: true },

{ id: 2, text: 'Build something', done: false },

{ id: 3, text: 'Ship it!', done: false },

]);

const newText = atom('');

const toggle = (id) => items.set(list =>

list.map(i => i.id === id ? { ...i, done: !i.done } : i)

);

const add = () => {

if (!newText().trim()) return;

items.set(list => [...list, { id: Date.now(), text: newText(), done: false }]);

newText.set('');

};

const remove = (id) => items.set(list => list.filter(i => i.id !== id));

return () => html`

<input

.value=${newText()}

@input=${e => newText.set(e.target.value)}

@keydown=${e => e.key === 'Enter' && add()}

placeholder="Add item…"

class="m-flex-1"

</div>

${repeat(items(), i => i.id, i => html`

API — repeat

import { html, repeat } from 'mates'

Prop / Option	Type	Default	Description
`repeat(items, keyFn, templateFn)`*	`DirectiveResult`	—	Key-based list reconciliation. Reuses and moves DOM nodes when the list changes.
`items`*	`Iterable`	—	Array or iterable to render.
`keyFn`*	`(item: T, index: number) => unknown`	—	Stable unique key per item (e.g. item.id). Tracks identity across renders.
`templateFn`*	`(item: T, index: number) => TemplateResult`	—	Returns the html`` template for each item.

.map() vs repeat()

Prop / Option	Type	Default	Description
items().map(i => html`...`)	`TemplateResult[]`	—	Simple and readable. Recreates DOM for items that move. Fine for short or append-only lists.
repeat(items(), keyFn, i => html`...`)	`DirectiveResult`	—	Key-based reconciliation. Moves nodes on reorder/insert — better for long, frequently mutated lists.

When lists get huge

Prop / Option	Type	Default	Description
`virtualList from mates-virtual`	`directive`	—	Windowed rendering — see /docs/directives/virtual. Same keyFn + template mental model.