References

Quick reference for all Flow JSX props, client expressions, and decorator combinations.

Commands

@zerotal/flow ships one generator:

JSX props reference

Write these as ordinary JSX attributes. The right-hand column shows what each compiles to, for when you're inspecting rendered HTML.

Event binding

Two-way binding

Validation

Reactive attributes

Loading states

Visual loading indicators (showOnLoading, hideOnLoading, loadingClass) wait out a short delay (~200ms) so a fast action never flashes them; loadingAttr is applied immediately (double-click guard).

Visibility and control

Navigation props

Polling

Streaming props

Intersection and visibility

Offline states

The client keeps a live WebSocket; when it drops (and while it reconnects with exponential back-off), Flow flips body[data-flow-connection] to offline and the props below react. Actions taken while offline are queued and replayed in order on reconnect, so the UI keeps working through a blip.

Recovering from a drop mid-action

If the connection drops while an action is in flight, the client cannot tell whether it ran. The server is stateless per frame, so a completed action has already committed its database write — while the browser is still holding the state from before it. Guessing either way is wrong: replaying risks doing the work twice, discarding loses it.

So Flow re-derives instead. Any component left mid-action is refreshed from the server on reconnect (onMount() runs again and a fresh patch comes back), which lands on the truth whether the action ran or not. The same applies when an acknowledgement simply times out.

The refresh is announced first, so you can say something rather than have the UI change under the user:

document.addEventListener("flow:desync", (e) => {
  const { components } = (e as CustomEvent<{ components: string[] }>).detail;
  toast(`Reconnected — refreshing ${components.length} component(s).`);
});

Transitions

Tune the duration with the --flow-transition-duration CSS variable (default 200ms).

Drag-and-drop reordering

Mark a container with onSort (the reorder action) and each child with sortItem (its stable key). Dragging a child calls the action as reorder(key, newIndex) on drop.

@expose async reorder(key: string, index: number) {
  const moved = this.items.find((i) => String(i.id) === key);
  if (!moved) return;
  this.items = this.items.filter((i) => i !== moved);
  this.items.splice(index, 0, moved);
  await this.persistOrder();
}

override async render() {
  return (
    <ul onSort={this.reorder}>
      {this.items.map((it) => (
        <li key={String(it.id)} sortItem={String(it.id)}>{it.name}</li>
      ))}
    </ul>
  );
}

A dynamic sortItem={String(it.id)} inside a .map() renders through the standard runtime (not the AOT fast path) — the drag behaviour is identical either way.

The payload does not say which container took the drop. The client reads flow:sort off the container a child was dropped into and calls it (key, index) — so the destination is encoded in which method runs, and nowhere else. For a single sortable list that is invisible. For dragging between containers under one sortGroup it means one action per container:

<ul onSort={this.dropInTodo} sortGroup="tasks">…</ul>
<ul onSort={this.dropInDone} sortGroup="tasks">…</ul>

An arrow (onSort={(k, i) => this.move("todo", k, i)}) cannot stand in, because the attribute's value is used as a method name rather than evaluated. onSort accepts the name as a string, so the handlers can come from a lookup table keyed by column, but they must be declared members.

DOM utilities

Alpine plugins

Escape hatch

Client expressions

Inside a client expression — onClick={() => this.X(...)} — this. resolves to the live client runtime (no server round-trip to start it). You write the same names as on the server — no $-prefixed syntax, and it all type-checks.

State manipulation

A write syncs to the server after the expression finishes, unless the same expression also calls a server action (that action's round-trip already carries it) or the value ends back where it started. Client-only UI state belongs in this.store(), which never round-trips.

Querying state

Navigation props and lifecycle

currentUrl() / navigateCurrent() merge query params onto the current URL: listed params are added/updated, unlisted ones preserved, and a null/undefined/"" value removes a param. Use currentUrl() in a binding (href={this.currentUrl({ query: { page: this.page + 1 } })}) and navigateCurrent() in a handler (onChange={(e) => this.navigateCurrent({ query: { status: e.target.value || null } })}). Both are client-only — they throw if called from server code. See Query-aware navigation.

Event dispatch

Parent interaction

Global client store

$flow.store is app-wide UI state that shouldn't round-trip to the server — side-panel visibility, colour scheme, notification drawer, etc. Declare its shape with defineStore(...) at app start and type it by augmenting FlowStore (see The global client store):

<button onClick={() => ($flow.store.ui.sidebarOpen = true)}>Open sidebar</button>
<aside show={$flow.store.ui.sidebarOpen}>Sidebar content</aside>

Decorator quick reference

Lifecycle hook quick reference

FlowTest assertion reference