Templating

Structural directives

A structural directive is a $-prefixed attribute. It goes on the element it applies to, or on a <template> to apply to a group of siblings. The $ is deliberate: bindings (from:x, bind:x, on:x) set or wire values; a $ directive changes whether, how many times, or in what scope markup is produced. At lowering the directive is evaluated and removed, so it never appears in the output (rendered DOM, compiled component, or serialized HTML alike), which is why its attribute name is free to be a directive.

<li $each="p of products">…</li>          <!-- iterate this element -->
<p  $if="cart.items.length">…</p>          <!-- guard this element -->
<td $value="user.name"></td>               <!-- escaped text content -->

<!-- multi-way and scope are directives too, on an element or a <template> -->
<template $match>
  <p $when="a">…</p>
  <p $else>…</p>
</template>

Inline text expressions

Authored template text inserts a value with {expression}. Every insertion has explicit opening and closing braces, including a simple path such as {$user.name}. Each expression uses the same scope, reactive dependencies, escaped-text conversion, absent-value behavior, and invalid-result retention as $value. Surrounding text and elements are preserved, with no wrapper element. For a sole read, <td>{$r.name}</td> and <td $value="$r.name"></td> have the same observable output.

<table><tbody>
  <tr $each="r of $rows" $key="$r.id"><td>{$r.name}</td></tr>
</tbody></table>

<p>Total: {$cart.total} due today</p>
<p>Hello, {$user.name}!</p>
<p>Download: {$file.name}.txt</p>
<p>Price: $1.15. The text $ident stays literal.</p>

Outside braces, $ is ordinary text: $ident, $HOME, and $1.15 do not read values and need no escape. In authored text, \{ emits a literal opening brace and \\ emits a literal backslash; other backslashes remain literal, including \$. These are text escapes, not identifier escapes. $value and $html continue to own their element's content when present.

$if: single guard

$if="expr" instantiates the element (or a <template>'s content) only when expr is truthy. It is a single guard with no else; multi-way branching is $match. The single-guard / multi-way split follows XSLT's xsl:if versus xsl:choose, rather than an imperative if/else if/else.¹

<p $if="cart.items.length">You have items in your cart.</p>

<!-- guard several siblings at once via a <template> -->
<template $if="cart.items.length">
  <h2>Your cart</h2>
  <ul>…</ul>
</template>

$each: iteration

$each="item of items" instantiates once per element of items, binding item in a fresh scope layer (with an optional index, $each="item, i of items"). The value uses the for…of grammar, one bounded, familiar form, not a packed micro-syntax. Iteration shaping is expressed as sibling $ modifiers, following XSLT's xsl:sort living inside xsl:for-each rather than a value pipeline.¹

$sort takes a comma-separated list of keys, each optionally prefixed with - for descending, so $sort="p.price,-p.name" orders by price ascending then name descending, the convention JSON:API's sort parameter² and Django's order_by³ use.

<li $each="p of products"
    $where="p.inStock" $sort="p.price,-p.name" $limit="10" $key="p.id">
  {$p.name}
</li>

<!-- index alias, when needed -->
<li $each="p, i of products">…</li>

$match / $when / $else: multi-way choice

A multi-way decision is a container carrying $match whose direct children are arms: each child with $when="expr" is a conditional arm, the first truthy one wins, and a child with $else is the terminal fallback. On a <template> the container itself renders nothing (only the winning arm does); on a real element the element wraps the winner.

<template $match>
  <progress $when="order.pending">Placing order…</progress>
  <output   $when="order.error">{$order.error.message}</output>
  <p        $else>Thanks for your order.</p>
</template>

Optional scope

$match="expr as name" binds a subject value once for every arm, the way $with does, using the same as grammar. Bare $match rebases nothing.

<!-- optional scope: bind the subject once, for every arm -->
<template $match="account.plan as plan">
  <span $when="plan.tier = 'pro'">{$plan.seats} seats</span>
  <span $else>Free plan</span>
</template>

Multi-way among rows and options

Because the arms are direct children of the <template>, not wrapped in a <when> element, a <tr> or <option> arm keeps its table/select context and survives, the case the old element form could not express.

<!-- multi-way among rows: arms are direct <template> children, so they survive -->
<table><tbody>
  <template $match>
    <tr $when="row.error" class="err"><td>{$row.message}</td></tr>
    <tr $else><td>{$row.name}</td></tr>
  </template>
</tbody></table>

$with: scope alias

Introducing a value under a name is a separate, visible operation. $with="expr as name" binds expr to name for the element's children (use it on a <template> for a wrapper-free scope). It takes an explicit alias rather than spreading the value's members as bare names: spreading reproduces the JavaScript with statement's ambiguity about where a name resolves, and defeats static scope analysis (see Scope & name resolution).

<section $with="account.owner as owner">
  <p>{$owner.name}</p>   <!-- owner is in scope here -->
</section>

Output: inline text, $value, and $html

Authored text evaluates expressions only inside {expression}. $value="expr" sets an element's whole text content, and <template $value="expr"> places wrapper-free text among siblings. All text forms share the same expression scope, reactivity, absence behavior, invalid-value retention, and escaping. Formatting uses format() in any expression (see Expressions).

<td>{$user.name}</td>
<p>Hello {$user.name}, welcome.</p>
<p>Total: {format($cart.total, 'currency', { currency: 'USD' })}</p>
<output $value="format($cart.total, 'currency', { currency: 'USD' })"></output>
<article $html="post.body"></article>

Expression boundaries and errors

A single opening brace starts an expression; its matching closing brace ends it. String literals and nested object braces are part of the expression and do not terminate it. All ordinary expression syntax is available, including computed indexes, conditionals, and fixed function calls. Empty, malformed, or unterminated expressions and undeclared roots are conformance errors. These author errors follow the same diagnostic and compile-time rejection policy as $value (see expression fault tolerance); braces never request a literal-text fallback. Write \{ for a literal opening brace. Interpolation applies to authored template text, not attributes, styles, plain projected content, returned strings, or dynamic HTML.

<p>{format($amount, 'currency', { currency: $currency }, $locale)}</p>
<p>{default($items[$selected].name, 'Unknown')}</p>
<p>Literal: \{format($amount)} and $amount</p>

Mixed literal text and expression segments retain one native text node per authored text node. Each segment retains its own last accepted value when a typed read or built-in operation becomes invalid; a segment with no accepted value remains empty. An absent or null result clears the segment, as it does for $value. Adjacent markup and text-node identity survive updates and hydration.

Whitespace & mixed content

HTML Next does not transform the whitespace an author writes. A template is HTML, so its whitespace is HTML whitespace: the parser preserves the text nodes, and runs of spaces, tabs, and newlines collapse at render time through CSS (white-space)⁶, exactly as they do in a hand-written .html file. There is no condensing pass, no whitespace flag, and nothing to learn: indent your source however reads best, and CSS collapses it the same way it always has. To keep whitespace, reach for CSS (white-space: pre, <pre>); to space things out, reach for CSS (gap, margins), never for whitespace-as-layout.

<!-- Whitespace is HTML's. The space around the value is significant and stays. -->
<p>Total: {$cart.total} due today</p>

<!-- Indentation and line breaks are preserved as text nodes, then collapse at
     RENDER through CSS white-space — exactly as in a hand-written .html file,
     not through a template build step. -->
<ul>
  <li $each="t of tags">{$t}</li>
</ul>

<!-- Opt out the way any HTML page does: with CSS, not a template flag. -->
<pre style="white-space: pre">  spaces and newlines, kept  </pre>

<!-- $value / $html own the element's whole content: authored children
     alongside them are a conformance error, never a silent merge. -->
<p $value="user.name">welcome</p>   <!-- ✗ text child + $value -->

Text expressions, elements, and <template $value> interleave as ordinary mixed content. The space in Total: {$cart.total} is significant and is preserved; $each emits the whitespace inside and around it like any repeated markup, with no join or separator behaviour of its own. The one hard rule is the content-owning directives: $value and $html set an element's entire content, so authored children beside them are a conformance error rather than a silent merge, the same constraint a content-replacing property binding carries.

Parser contexts

Because control flow is entirely $ attributes, it survives every parser context, including the restrictive ones (<table>, <select>, SVG/MathML) where a hyphenless element would be foster-parented out or dropped. A group of siblings rides a <template>, which is valid everywhere and parses its contents permissively.

<!-- every $ directive is an attribute, so it survives every parser context -->
<table><tbody>
  <tr $each="r of rows" $key="r.id"><td>{$r.name}</td></tr>
</tbody></table>

<select>
  <option $each="o of opts" from:value="o.id">{$o.label}</option>
</select>

<!-- a fragment (several siblings) rides a <template> -->
<table><tbody>
  <template $each="r of rows">
    <tr class="head"><td>{$r.title}</td></tr>
    <tr class="body"><td>{$r.detail}</td></tr>
  </template>
</tbody></table>

Reference

References

1. W3C, XSL Transformations (XSLT) 3.0 (xsl:if, xsl:choose/when/otherwise, xsl:sort).
2. JSON:API, sorting (the sort=a,-b convention).
3. Django, QuerySet.order_by (the same --prefix descending convention).
4. Shopify Liquid and Twig (the unless tag HTML Next omits).
5. WHATWG HTML, the HTML Sanitizer API (the safe-default policy on which $html is based).
6. W3C, CSS Text Module Level 3 (the white-space processing and collapsing model HTML Next defers to at render).
7. Angular structural directives (*ngIf/*ngFor): control flow expressed as a directive on the context-valid element rather than a wrapper element, the same parser-survival property argued here. Contrast: Svelte {#if}/{#each} and Solid Show/For are wrapper or block forms that do not survive <table>/<select> foster-parenting.
8. Angular @switch/@case/@default blocks: a near-exact twin of $match/$when/$else, alongside the XSLT xsl:choose unit.