States

A state is a named branch of the widget's UI that's either always visible or visible only when a variable equals a given value. Define states on the States tab, then render one by wrapping part of the ast in a State component node.

Defining a state

Each state branch has:

Field	Type	Description
name	string	Required. The editor requires it to match /^[a-zA-Z_][a-zA-Z0-9_]*$/; specs written directly as JSON or through the API are not checked against that pattern, so follow it anyway.
when	{ variable: string, equals: unknown } | null	When null (or omitted), the branch is always visible. Otherwise, visible only while variable strictly equals equals (===, without type coercion). Use scalar comparisons such as strings, numbers, or booleans.

In the States tab UI, a branch's Visibility is either "Always visible" or "Conditional"; picking "Conditional" adds a When variable / Equals pair, with the Equals input adapting to the chosen variable's type (a switch for boolean, a number input for number, otherwise text).

Rendering a state

Reference a state in the ast with a State component node — its props.name must match a declared state's name, and its children are rendered only while the state is visible. An unknown state name renders no children:

{
  "component": "State",
  "props": { "name": "optionsView" },
  "children": [
    { "component": "Text", "props": { "value": "Choose an option below" } }
  ]
}

Given a state declared as:

{ "name": "optionsView", "when": { "variable": "step", "equals": "options" } }

the State node above renders its children only while the step variable currently equals "options". If step changes (for example, via a setVariable function wired to a button), the widget re-renders and the branch shows or hides accordingly — in a remote-dom widget. See Widgets Overview for how content type affects whether a widget updates after the first render.

Common pattern: tabs or multi-step flows

Declare one variable to track the active step (e.g. step, type string, default: "intro"), one state per step (each when: { variable: "step", equals: "<step name>" }), and one setVariable function per navigation button to advance step to the next value.