Earlier formats

Dynamic props and actions

Read and write on-page state with $state, $bindState, $template, $cond, visible, repeat, and the five state actions.

Any prop can be a dynamic value: an object with one special key that resolves when the page renders. Dynamic values read the spec's state, written as JSON Pointer paths such as /build/status. Validation skips the schema check for a prop that holds an expression, and the renderer checks it again once it resolves: a value of the wrong type shows a small notice in place of that element only.

$state: read stateLink to this section

{ "$state": "/path" } reads a value from state.

Read state with $state

Build

passing
Tests412 of 418
Show JSON
{
  "version": 1,
  "root": "card",
  "elements": {
    "card": {
      "type": "Card",
      "props": { "title": "Build" },
      "children": ["status", "progress"]
    },
    "status": {
      "type": "Badge",
      "props": { "label": { "$state": "/build/status" }, "tone": "success" }
    },
    "progress": {
      "type": "Progress",
      "props": {
        "label": "Tests",
        "value": { "$state": "/build/passed" },
        "max": { "$state": "/build/total" },
        "format": "fraction"
      }
    }
  },
  "state": { "build": { "status": "passing", "passed": 412, "total": 418 } }
}

$bindState: two-way inputsLink to this section

{ "$bindState": "/path" } on an input's value prop (checked on Checkbox and Switch, value on Select and Slider) reads the path and writes it back when the reader changes the input. Anything else that reads the same path updates at once. Inside a repeat, { "$bindItem": "field" } binds to a field of the current item.

An input bound to state

Move the slider: it writes /percent, and the bar and the text read it.

Rollout30
Users on the new version30%

30% of users get the new checkout.

Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "md" },
      "children": ["slider", "bar", "line"]
    },
    "slider": {
      "type": "Slider",
      "props": {
        "label": "Rollout",
        "min": 0,
        "max": 100,
        "step": 10,
        "value": { "$bindState": "/percent" }
      }
    },
    "bar": {
      "type": "Progress",
      "props": {
        "label": "Users on the new version",
        "value": { "$state": "/percent" }
      }
    },
    "line": {
      "type": "Text",
      "props": {
        "size": "sm",
        "tone": "muted",
        "text": { "$template": "${/percent}% of users get the new checkout." }
      }
    }
  },
  "state": { "percent": 30 }
}

$template: text with valuesLink to this section

{ "$template": "Hi ${/name}" } builds a string. ${/path} reads state; inside a repeat, a bare name such as ${owner} reads the current item first.

Interpolate state into text
Team

Platform owns 3 open incidents.

Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["team", "line"]
    },
    "team": {
      "type": "Select",
      "props": {
        "label": "Team",
        "options": ["Platform", "Web", "Data"],
        "value": { "$bindState": "/team" }
      }
    },
    "line": {
      "type": "Text",
      "props": {
        "text": { "$template": "${/team} owns ${/count} open incidents." }
      }
    }
  },
  "state": { "team": "Platform", "count": 3 }
}

$cond: pick a valueLink to this section

{ "$cond": <condition>, "$then": a, "$else": b } picks one of two values. Conditions use the same forms as visible, below.

Pick a tone and a label from state
Environment
Safe to test
Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["env", "badge"]
    },
    "env": {
      "type": "Select",
      "props": {
        "label": "Environment",
        "options": ["Production", "Preview", "Development"],
        "value": { "$bindState": "/env" }
      }
    },
    "badge": {
      "type": "Badge",
      "props": {
        "label": {
          "$cond": { "$state": "/env", "eq": "Production" },
          "$then": "Live traffic",
          "$else": "Safe to test"
        },
        "tone": {
          "$cond": { "$state": "/env", "eq": "Production" },
          "$then": "danger",
          "$else": "success"
        }
      }
    }
  },
  "state": { "env": "Preview" }
}

visible: show and hideLink to this section

visible sits on the element, next to props, not inside them. The element and its children render only while the condition holds.

ConditionMeaning
{ "$state": "/open" }The value at /open is truthy.
{ "$state": "/tab", "eq": "a" }Equal. Also neq.
{ "$state": "/bugs", "gt": 5 }Greater than. Also gte, lt, and lte.
{ "$state": "/open", "not": true }Inverts the result.
[ cond, cond ]Every condition holds (and).
{ "$and": [ … ] } / { "$or": [ … ] }All of them, or any of them.
{ "$item": "done", "eq": true }Inside a repeat: a field of the current item.
{ "$index": true, "eq": 0 }Inside a repeat: the item's position.
Show an element only when a condition holds
Open bugs3

Under the release bar. Ship it.

Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["count", "ok", "warn"]
    },
    "count": {
      "type": "Slider",
      "props": {
        "label": "Open bugs",
        "min": 0,
        "max": 20,
        "value": { "$bindState": "/bugs" }
      }
    },
    "ok": {
      "type": "Callout",
      "props": { "tone": "success", "text": "Under the release bar. Ship it." },
      "visible": { "$state": "/bugs", "lte": 5 }
    },
    "warn": {
      "type": "Callout",
      "props": {
        "tone": "warning",
        "text": "Over the release bar of 5 open bugs."
      },
      "visible": { "$state": "/bugs", "gt": 5 }
    }
  },
  "state": { "bugs": 3 }
}

repeat and $item: lists from stateLink to this section

{ "repeat": { "statePath": "/items", "key": "id" } } renders the element's children once per item of a state array. key is optional: name a field that is unique per item so React keeps each row's place. Inside, read fields with { "$item": "name" } and the position with { "$index": true }.

  • A repeat cannot sit inside another repeat. Flatten the data into one array.
  • One repeat renders at most 200 items, and a whole spec at most 5,000 elements once repeats expand.
One card per item, with add and remove

Add services, then remove one: pushState and removeState change the /services array.

worker

Owner: Lee

Show JSON
{
  "version": 1,
  "root": "page",
  "elements": {
    "page": {
      "type": "Stack",
      "props": { "gap": "md" },
      "children": ["add", "list"]
    },
    "add": {
      "type": "Stack",
      "props": { "direction": "horizontal", "gap": "sm" },
      "children": ["add-api", "add-web"]
    },
    "add-api": {
      "type": "Button",
      "props": { "label": "Add api", "variant": "outline" },
      "on": {
        "press": {
          "action": "pushState",
          "params": {
            "statePath": "/services",
            "value": { "name": "api", "owner": "Ada" }
          }
        }
      }
    },
    "add-web": {
      "type": "Button",
      "props": { "label": "Add web", "variant": "outline" },
      "on": {
        "press": {
          "action": "pushState",
          "params": {
            "statePath": "/services",
            "value": { "name": "web", "owner": "Sam" }
          }
        }
      }
    },
    "list": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "repeat": { "statePath": "/services" },
      "children": ["item"]
    },
    "item": {
      "type": "Card",
      "props": {
        "title": { "$item": "name" },
        "description": { "$template": "Owner: ${owner}" }
      },
      "children": ["remove"]
    },
    "remove": {
      "type": "Button",
      "props": { "label": "Remove", "variant": "ghost" },
      "on": {
        "press": {
          "action": "removeState",
          "params": { "statePath": "/services", "index": { "$index": true } }
        }
      }
    }
  },
  "state": { "services": [{ "name": "worker", "owner": "Lee" }] }
}

ActionsLink to this section

on maps an event to one action or a list of actions that run in order. Events: Button: press · Input: change · Textarea: change · Checkbox: change · Select: change · Switch: change · Slider: change. Every other component has no events. The allowed actions are setState, pushState, removeState, toggleState, validateForm. Action params accept the same dynamic values as props.

ActionparamsWhat it does
setState{ "statePath": "/decision", "value": "Approved" }Writes a value at a path.
toggleState{ "statePath": "/open" }Flips a value between true and false, so one button opens and closes.
pushState{ "statePath": "/items", "value": { … }, "clearStatePath": "/draft" }Appends to an array. clearStatePath, if given, is set to an empty string afterwards.
removeState{ "statePath": "/items", "index": { "$index": true } }Removes one array item by position.
validateForm{ "statePath": "/review" }Writes { valid, errors } to the path (default /formValidation).
Two actions on one pressjson
{
  "on": {
    "press": [
      {
        "action": "setState",
        "params": { "statePath": "/step", "value": 2 }
      },
      {
        "action": "pushState",
        "params": { "statePath": "/log", "value": { "$state": "/draft" } }
      }
    ]
  }
}

setStateLink to this section

Buttons that set state

Decision: none yet

Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["choices", "answer"]
    },
    "choices": {
      "type": "Stack",
      "props": { "direction": "horizontal", "gap": "sm" },
      "children": ["approve", "hold"]
    },
    "approve": {
      "type": "Button",
      "props": { "label": "Approve" },
      "on": {
        "press": {
          "action": "setState",
          "params": { "statePath": "/decision", "value": "Approved" }
        }
      }
    },
    "hold": {
      "type": "Button",
      "props": { "label": "Hold", "variant": "outline" },
      "on": {
        "press": {
          "action": "setState",
          "params": { "statePath": "/decision", "value": "On hold" }
        }
      }
    },
    "answer": {
      "type": "Text",
      "props": { "text": { "$template": "Decision: ${/decision}" } }
    }
  },
  "state": { "decision": "none yet" }
}

pushState and removeStateLink to this section

The repeat example above uses both: each Add button pushes an object onto /services, and each Remove button removes its own item with { "$index": true }.

validateFormLink to this section

Mark a form as checked

Press Check: validateForm writes { valid, errors } to /review. The stout inputs declare no field checks, so valid is true.

Show JSON
{
  "version": 1,
  "root": "stack",
  "elements": {
    "stack": {
      "type": "Stack",
      "props": { "gap": "sm" },
      "children": ["agree", "check", "result"]
    },
    "agree": {
      "type": "Checkbox",
      "props": {
        "label": "I read the runbook",
        "checked": { "$bindState": "/agreed" }
      }
    },
    "check": {
      "type": "Button",
      "props": { "label": "Check" },
      "on": {
        "press": [
          {
            "action": "validateForm",
            "params": { "statePath": "/review" }
          },
          {
            "action": "setState",
            "params": { "statePath": "/checked", "value": true }
          }
        ]
      }
    },
    "result": {
      "type": "Callout",
      "props": {
        "tone": "success",
        "text": { "$template": "Checked. Valid: ${/review/valid}." }
      },
      "visible": { "$state": "/checked" }
    }
  },
  "state": { "agreed": false, "checked": false }
}

What is not supportedLink to this section

  • $computed: it needs app functions, and none are registered.
  • watch and named slots on an element.
  • Any action that is not in the list above. Nothing on a page can fetch, send, navigate, or save.
  • Keys or state paths that use __proto__, constructor, or prototype.
Validation names each of these with the element key and the fix. See Validation.