Guide

Show and For

Content that appears and disappears, and keyed lists that keep each node while its key is still there.

<Show>

ts
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:

ts
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>

ts
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:

ts
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:

ts
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.

ts
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.

ts
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.