Guide
Show and For
Content that appears and disappears, and keyed lists that keep each node while its key is still there.
<Show>
view`
<div class="app">
<Show when=${() => session() !== null}>
<Panel session=${() => session()!}/>
<Else>
<Login onlogin=${(s: Session) => session.set(s)}/>
</Else>
</Show>
</div>`;when is the only reactive part. Each branch is built when it is shown:
the one that is not visible does not exist yet, neither its nodes nor its
effects. When the condition changes, the previous branch is released whole
—effects, memos, listeners, onCleanup— and the other one is built.
If when returns the value it already had, nothing is rebuilt: toggling a
boolean that was already true does not touch the DOM. It compares the
value, not its truthiness: if when goes from 1 to 2, the branch is
rebuilt even though both are truthy. To avoid that, have it return a boolean:
when=${() => items().length > 0}.
<Else> is optional, goes inside the <Show> and there can be only one. A
branch can have several sibling nodes.
With the value
When the branch needs what when checked, the child can be a function that
receives it:
view`
<section>
<Show when=${() => club()}>
${(club) => view`<h2>${() => club().name}</h2>`}
<Else><p>No club.</p></Else>
</Show>
</section>`;club is an already narrowed accessor: if outside club() is a
Club | undefined, inside it is a Club, with no !, ?. or ?? "".
"Nothing" is null, undefined or false; a 0 or an empty string count as
a value.
when can be a closure or anything callable: when=${club} with a signal or a
resource works the same. The child has to be a function that receives the
accessor: ${(c) => Tarjeta(c)}, not a bare ${Tarjeta}, which would be
text —and ascua-check flags it as an error—. In a generic component the
parameter can be annotated, ${(d: () => Present<T>) => …}; this needs
TypeScript 5.4 or later.
And the branch is rebuilt only when the value appears or disappears. If it changes to another one —a poll that brings the club again every fifteen seconds, in a new object—, what reads it inside updates without redoing anything.
<For>
view`
<ul class="tasks">
<For each=${() => tasks()}
key=${(t: Task) => t.id}
render=${(t: Task) => view`<li>${t.title}</li>`}/>
</ul>`;| Prop | What it is |
|---|---|
each |
A closure that returns the array. It is the reactive part. |
key |
What identifies each item. It has to be unique. |
render |
Builds the node for one item. |
render runs once per key. While a key stays in the list, its node is kept
and, if needed, moved; it is not rebuilt. That preserves what the framework
does not control: focus, selection, scroll, an <input> half typed.
Moving as little as possible
When the list changes order, the rows that keep the same relative order stay put and only the others move —the ones outside the longest increasing subsequence of the previous positions—. Swapping two rows out of a thousand is two DOM moves; moving one to the end, one. And emptying a list that is alone in its parent is a single operation, not a thousand.
Items that change
Since the node for each key is not redone, for the content of an item to change, the item has to read a signal on its own:
interface Order {
id: number;
status: Signal<"pending" | "shipped">;
}
render=${(p: Order) => view`
<li data-status=${() => p.status()}>#${p.id}: ${() => p.status()}</li>`}Advancing an order writes to one text node and one attribute, and neither the list nor the other rows find out.
Data that arrives whole: the second parameter
The above works when the state is yours. When the data comes from a server —a
poll every fifteen seconds—, each response brings new objects, and a row built
with the first one does not see the later ones: for the <For> it is the same
key. For that, render can take a second parameter:
render=${(c: Conversation, current: () => Conversation) => view`
<tr data-id=${c.id}>
<td>${c.patient}</td>
<td>${() => current().messages}</td>
<td class:active=${() => current().active}></td>
</tr>`}current() is the last object that arrived with that key, and it is reactive:
what reads it updates, without rebuilding the row or losing its focus. What
does not change is still read from the first one (c.id). With
ascua-query, a poll that brings the same data reuses
each object, so current() only notifies the rows that changed.
Without the second parameter there is no signal per row: you do not pay for what you do not use.
The selected row
If each row reads a "which one is selected" signal, changing it wakes all of
them. That is what
selector is
for: each row listens only to its key.
Where to anchor them
<Show> and <For> leave an invisible marker —a comment— inside their parent
and place their content before it. That is why they need a parent element:
they cannot be the root of a template. They can share a parent with other
nodes.
view`<Show when=${…}>…</Show>`; // ✗ no parent
view`<section><Show when=${…}>…</Show></section>`; // ✓Inside the branch of another <Show> you do not need an element in between:
the parent is the one of the outer region.
view`
<tbody>
<Show when=${() => loading()}>
<tr><td>Loading…</td></tr>
<Else>
<Show when=${() => rows().length === 0}>
<tr><td>No results.</td></tr>
<Else><For each=${rows} key=${(r: Row) => r.id} render=${RowView}/></Else>
</Show>
</Else>
</Show>
</tbody>`;A <div> there would break the table. When the outer branch closes, it takes
whatever is inside with it, even if it changed since it was shown.