Bindings & Events

The binding family

An unprefixed attribute is a literal. A prefix marks a binding. The colon is verified across Chromium, Firefox, and WebKit to be an ordinary attribute-name character (not an XML namespace), so every form survives the parser and round-trips through outerHTML.

The shapes have direct framework precedent³: the :attr one-way form echoes Vue v-bind, while bind: (two-way) and on: (event) match Svelte verbatim. Angular [(ngModel)], its banana-in-a-box, is the canonical one-way-in-plus-event-out two-way model that the bind: writability rules follow.

One-way bindings

:name="expr" binds an attribute or a contract-declared property. It normalizes before resolving: strip the marker, ASCII-lowercase the remainder, look the key up in the generated platform manifest, and assign using the returned canonical spelling, which may be an attribute or a DOM property. There is deliberately no separate raw-property syntax: the manifest is authoritative, so an author never hand-picks an exact IDL name, and no binding reaches an arbitrary DOM property outside the contract.

Replacing an element's content is not a binding but a templating directive: escaped text is $value, sanitized markup is $html. Raw, unsanitized HTML is available only through the dedicated trusted-HTML type (see Types), never an ordinary string.

How a bound value serializes

A binding evaluates to a typed value, and how that value lands depends on the value and the attribute's kind (the generated manifest carries each attribute's kind). One default rule covers almost everything:

The false/null → removed rule is what makes boolean attributes work with no special case: :disabled="isDisabled" adds disabled when true and removes it when false, never the disabled="false" trap (which is actually disabled). When you want the characters "false", bind a string, :data-state="'false'", or an identifier that resolves to one.

Because the mapping is fixed and manifest-driven, every target serializes identically, the equivalence contract applied to attribute writes: the polyfill and the React/Vue/Svelte outputs each compile to their own idiom while producing the same observable attribute.

Two-way binding: bind:

bind:prop="path" reflects the value and writes user input back to path. It is the forms workhorse, and it requires a writable path plus an element contract that supports updates.

<input bind:value="search.query">
<input type="checkbox" bind:checked="filters.inStock">

What counts as writable

A writable path is a member or index access chain rooted at a <state> cell, the only mutable source. Everything else is read-only, and bind: to it is a conformance error, caught statically because the root's declaration is known:

Writability flows from the root: a $each local or $with alias is writable exactly when it aliases a writable path, an item of a <state> collection is, an item of a <data> collection is not. Writing a sub-path updates that path in the state cell and re-runs its dependents; the implementation may model state as mutable-with-tracking or as a structural update, the observable result is the same.

Class & style bindings

Conditional presentation uses keyed bindings, one class token or style property at a time, joining the same family as on: and bind:. class:btn--busy="saving" adds the class when the expression is truthy; style:--progress="pct + '%'" sets that property to the expression's value. The key is the attribute name (a literal class token or CSS property) and the value is a single pure expression, so nothing packs a key/value list into one attribute value,⁴ and the only : is the family prefix while the only = is equality inside the expression. Both compose with any literal class or style. Purely visual transforms remain CSS's job (see Styling); these only toggle which classes and custom properties apply.

<!-- one class or style property per keyed binding; the value is a single pure expression -->
<button class="btn" class:btn--busy="saving" class:btn--danger="variant = 'destructive'">
<div style:--progress="upload.percent + '%'"></div>

Events & handlers

on:event="handler" wires a DOM event to a declared handler. The form echoes native onclick and joins the binding family, but the browser does not execute on:click as script: the value names a <handler>, it is not an expression. Behavior and visible markup stay cleanly separated, the handler lives in the definition's <defs> region (see Components), the content just points at it by name.

<!-- content references behavior by name; no steps inline -->
<button type="button" on:click="startEdit">Edit</button>

<form on:submit.prevent="save">
  <input bind:value="draft.title">
  <button>Save</button>
</form>

<!-- behavior lives in the definition's <defs> region -->
<defs>
  <handler name="startEdit">
    <set name="editing" :value="true">
  </handler>

  <handler name="save">
    <set name="saving" :value="true">
    <dispatch event="saved" :value="draft">
  </handler>
</defs>

Handler steps

A handler is an ordered, enumerable list of declarative steps. The vocabulary is deliberately tiny, and none of it reaches into userland code.

Platform verbs: native invoker commands

Opening a dialog or toggling a popover is not component logic, it is a platform verb on a specific element. The platform already ships the declarative answer: invoker commands (command / commandfor), shipped in Chromium, WebKit, and Firefox.¹ Use them directly, HTML Next adds nothing here.

<!-- platform verbs: native invoker commands, no <handler> block needed -->
<button command="show-modal" commandfor="editor">Edit</button>
<dialog id="editor">…</dialog>

<button command="toggle-popover" commandfor="menu">Menu</button>
<div id="menu" popover>…</div>

Modifiers & component events

A handler runs as declarative steps, so the operations you would otherwise call on the event object, preventDefault, stopPropagation, and the addEventListener options, have no imperative place to live. They ride the event name as dotted modifiers, each naming a real DOM operation: on:submit.prevent, on:click.stop, on:click.once, on:scroll.passive, on:click.capture. The dotted syntax itself is Vue's prior art, not an HTML native; key filters such as on:keydown.enter are convenience layered on top. A component declares emitted events in its contract; a consumer listens with the same form: <x-dialog on:saved="refresh">, where refresh is one of its own handlers. The same on: family carries the lifecycle events on:connect/on:disconnect (see Lifecycle).

Keys

$key="expr", a modifier on $each (see Templating), gives each iterated item a stable identity, so reactive updates and reordering are correct rather than index-positional. Keyed reconciliation is well-trodden prior art⁵: React introduced key, and Vue, Svelte, Angular, and Lit each carry their own form.

Replacing ref

Frameworks expose a ref handle so imperative code can reach a node. HTML Next has no imperative handler, so there is nothing to dereference, and each concrete use of a ref maps to a declarative form:

The pattern: reading is bind:; platform verbs are invoker commands addressed by id (the way label[for] and [aria-controls] already cross-reference); and the residual imperative cases are an acknowledged open area, not a hidden ref.

Non-conforming

Element reference

References

1. WHATWG HTML, invoker commands (command/commandfor); see also MDN: Invoker Commands API.
2. WHATWG DOM, dispatching events (the dispatch verb behind <dispatch>).
3. Binding-family prior art: Vue v-bind (the :attr one-way shorthand HTML Next borrows); Svelte bind: and on: element directives (two-way and event, matched here verbatim); Angular two-way binding (the [(ngModel)] banana-in-a-box: one-way-in plus event-out, the model behind the bind: writability rules).
4. Keyed presentation prior art: Svelte class: and style: directives (the exact keyed syntax adopted here). Contrast: Vue object :class="{ open: x }" and Lit classMap/styleMap pack a key/value map into one attribute value; Angular [class.x]/[style.x]/ngClass and Solid classList are the same keyed idea.
5. Keyed iteration prior art: React key (the origin of list identity), Vue :key, Svelte keyed each, Angular @for with track (and the older trackBy), and Lit repeat with a key function.