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.
Build
Show JSONHide 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.
Move the slider: it writes /percent, and the bar and the text read it.
30% of users get the new checkout.
Show JSONHide 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.
Platform owns 3 open incidents.
Show JSONHide 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.
Show JSONHide 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.
| Condition | Meaning |
|---|---|
| { "$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. |
Under the release bar. Ship it.
Show JSONHide 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.
Add services, then remove one: pushState and removeState change the /services array.
worker
Owner: Lee
Show JSONHide 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.
| Action | params | What 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). |
{
"on": {
"press": [
{
"action": "setState",
"params": { "statePath": "/step", "value": 2 }
},
{
"action": "pushState",
"params": { "statePath": "/log", "value": { "$state": "/draft" } }
}
]
}
}setStateLink to this section
Decision: none yet
Show JSONHide 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
Press Check: validateForm writes { valid, errors } to /review. The stout inputs declare no field checks, so valid is true.
Show JSONHide 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.watchand namedslotson 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, orprototype.