OpenUI

Reactive State

Keep UI state in $variables so the generated UI updates without another model call when the user changes something.

Reactive state makes a generated UI interactive: filters, tabs, and inputs respond to the user without another model call. The model declares a $variable and uses it in several places. When the user changes it, the renderer updates every place that reads it.

For example, a dashboard has a date range picker, a heading, and a chart. The user picks "30 days". The heading changes to "Showing last 30 days" and the chart fetches 30 days of data. The model wrote that wiring once, in the first response.

Declaring a variable

A $variable is a statement whose name starts with $:

$days = "7"
$title = ""
$showEdit = false

The value on the right is the default.

Binding to inputs

When a $variable is passed to an input's value prop, the two stay in sync. When the user changes the input, the variable updates. When the variable changes, the input shows the new value.

$days = "7"
filter = Select("days", [SelectItem("7", "7 days"), SelectItem("30", "30 days")], null, null, $days)

In openuiLibrary, value is the fifth argument of Select and Input, so the model writes null for the placeholder and rules it skips.

Using variables in expressions

Any expression can read a $variable:

title = TextContent("Showing last " + $days + " days")
data = Query("analytics", {days: $days}, {rows: []})

When the user picks "30" in the Select, $days changes. The renderer updates the title and fetches the Query again with the new value.

Changing state from buttons

@Set is an action that sets a variable when the button is clicked:

btn = Button("Show 30 days", @Set($days, "30"))

To set several variables, put several actions in Action([...]). They run in order:

saveBtn = Button("Save", Action([@Set($showEdit, false), @Set($saved, true)]))

Resetting to defaults

@Reset restores variables to their declared defaults:

$title = ""
$priority = "medium"
resetBtn = Button("Clear", @Reset($title, $priority))

After the click, $title is "" again and $priority is "medium".

Conditional rendering

A ternary shows or hides part of the UI based on state. The result must be assigned to a statement like any other expression:

$showHelp = false
helpBtn = Button("Help", @Set($showHelp, true))
help = $showHelp ? Callout("info", "Tip", "Pick a range to update the chart.") : null
root = Stack([helpBtn, help])

How reactivity works

How a $variable change spreadsThe user picks 30 days in a Select. The Select is bound to $days, which changes from 7 to 30. The TextContent that reads $days shows the new text. The Query that takes $days in its arguments fetches again with days 30, and the Chart that reads the Query's rows re-renders.SelectThe user picks"30 days"$days"7" → "30"SetsRe-evaluatesRe-fetchesTextContent"Showing last30 days"QueryFetches again with{days: "30"}ChartRe-renders withthe new rowsRows

When a $variable changes, the renderer:

  1. Updates every input bound to it.
  2. Fetches every Query that uses it in its arguments again.
  3. Re-evaluates every expression that reads it.
  4. Re-renders the components whose props changed.

The model declares the variable and uses it. The renderer keeps everything in sync.

Complete example

A usage dashboard where the date range drives the heading and the chart.

Your app renders the response with openuiLibrary and gives the renderer one tool:

"use client";

import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui";

export function Dashboard({ response }: { response: string }) {
  return (
    <Renderer
      library={openuiLibrary}
      response={response}
      toolProvider={{
        get_usage: async ({ days }) => fetch(`/api/usage?days=${days}`).then((r) => r.json()),
      }}
    />
  );
}

The model writes:

root = Stack([header, filter, summary, chart])
header = CardHeader("Usage")
$days = "7"
filter = FormControl("Date range", Select("days", [SelectItem("7", "7 days"), SelectItem("30", "30 days")], null, null, $days))
usage = Query("get_usage", {days: $days}, {rows: []})
summary = TextContent("Showing last " + $days + " days, " + @Sum(usage.rows.events) + " events")
chart = LineChart(usage.rows.day, [Series("Events", usage.rows.events)])

The user sees a "Usage" card with a date range picker set to "7 days", a summary line, and a line chart. When the user picks "30 days", the summary changes to "Showing last 30 days" and the renderer calls get_usage with { days: "30" }. The chart redraws with the new rows. The model is not called again.

What your component must do

The components in openuiLibrary already support $variable binding. A component in your own library supports it when it:

  1. Marks the prop with reactive(...), for example value: reactive(z.string().optional()).
  2. Reads and writes the value through useStateField(props.name, props.value) instead of local React state.

useStateField returns { value, setValue }. Calling setValue updates the $variable, and the renderer re-evaluates everything that reads it. See Interactivity for a full component.

When to use it

Use reactive state when:

  • A filter, tab, or toggle should change what the UI shows.
  • Form inputs feed a Query or Mutation.
  • A button should open a modal or show a section.

Do not use it when:

  • The change needs new reasoning or new layout from the model. Use @ToAssistant to send a message instead.
  • The value never changes. Use a plain statement, such as title = "Usage".

On this page