OpenUI

Queries & Mutations

Fetch and write data from your tools. The model writes the wiring, the runtime runs it.

Queries and mutations connect a generated UI to your backend. The model writes which tool to call and where the result goes. The runtime calls your tools directly, without the model.

For example, a support agent asks for "a table of open tickets with a form to add one". The model writes one Query that lists tickets and one Mutation that creates a ticket. The table fills from your API, and each new ticket appears in it after the user submits the form. No click goes through the model.

How a Query reaches your toolsThe program declares tickets = Query(list_tickets). On load, or when an action runs it with @Run, the runtime evaluates the arguments and calls the tool through toolProvider. Your tools, a function map or an MCP server, return rows. The runtime passes the rows to the components that read them, such as a table and a chart.OpenUI Langtickets = Query( "list_tickets", {}, {rows: []})On loador @RunRuntimeEvaluates theargumentstoolProvider{ rows: [...] }Your toolsFunction mapor MCP serverRowsYour componentsThe table and chartre-render with the rows

A tool is any function your app exposes: a database query, an API call, or a calculation. The model generates Query and Mutation statements that call these tools. The runtime runs them and feeds the results into your UI.

Reading data with Query

data = Query("list_tickets", {}, {rows: []})

What each argument means:

  1. "list_tickets": the tool name. It matches a tool your toolProvider exposes.
  2. {}: the arguments passed to the tool.
  3. {rows: []}: the default value. The UI renders it until the tool responds.

The default value lets the UI render while the data loads.

Using Query results

Query results are data. Access fields with dot notation:

tbl = Table([Col("Title", data.rows.title), Col("Status", data.rows.status)])
chart = LineChart(data.rows.day, [Series("Views", data.rows.views)])

data.rows.title takes the title field from every row, like a column pluck.

Reactive queries

Pass a $variable in the query arguments. The query runs again when the variable changes:

$days = "7"
data = Query("analytics", {days: $days}, {rows: []})
filter = Select("days", [SelectItem("7", "7 days"), SelectItem("30", "30 days")], null, null, $days)

The user picks "30", $days updates, the Query fetches again with {days: "30"}, and the chart updates.

Auto-refresh

A fourth argument sets a refresh interval in seconds:

health = Query("get_server_health", {}, {cpu: 0, memory: 0}, 30)

This fetches the data again every 30 seconds.

Writing data with Mutation

createResult = Mutation("create_ticket", {title: $title, priority: $priority})

A Mutation does not run when the page loads. It runs only when an action runs it with @Run:

submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title)]))

This button runs three actions in order:

  1. @Run(createResult) runs the mutation and creates the ticket.
  2. @Run(tickets) fetches the tickets query again, so the table refreshes.
  3. @Reset($title) clears the title field.

If the mutation fails, the actions after it do not run.

Error handling

Check result.status to show feedback. Assign each check to a statement and place it in the layout:

createError = createResult.status == "error" ? Callout("error", "Failed", createResult.error) : null
createDone = createResult.status == "success" ? Callout("success", "Created", "Ticket added.") : null

How tools connect to the runtime

The Renderer takes a toolProvider prop that runs the tools. Pass a function map or an MCP client. The Renderer is a client component, so these functions run in the browser. Point them at your API routes:

// Function map
<Renderer
  toolProvider={{
    list_tickets: async () => fetch("/api/tickets").then((r) => r.json()),
  }}
  response={code}
  library={library}
/>

// Or an MCP client
<Renderer toolProvider={mcpClient} response={code} library={library} />

Complete example

A ticket tracker with a create form and a table.

Your app gives the renderer two tools. Each calls an API route on your server:

"use client";

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

export function Tickets({ response }: { response: string }) {
  return (
    <Renderer
      library={openuiLibrary}
      response={response}
      toolProvider={{
        list_tickets: async () => fetch("/api/tickets").then((r) => r.json()),
        create_ticket: async (args) =>
          fetch("/api/tickets", { method: "POST", body: JSON.stringify(args) }).then((r) =>
            r.json(),
          ),
      }}
    />
  );
}

The model writes:

root = Stack([CardHeader("Tickets"), form, createError, tbl])
$title = ""
$priority = "medium"
tickets = Query("list_tickets", {}, {rows: []})
createResult = Mutation("create_ticket", {title: $title, priority: $priority})
form = Form("create", Buttons([submitBtn]), [titleField, priorityField])
titleField = FormControl("Title", Input("title", "Ticket title", "text", {required: true}, $title))
priorityField = FormControl("Priority", Select("priority", [SelectItem("low", "Low"), SelectItem("medium", "Medium"), SelectItem("high", "High")], null, null, $priority))
submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title, $priority)]), "primary")
createError = createResult.status == "error" ? Callout("error", "Could not create the ticket", createResult.error) : null
tbl = Table([Col("Title", tickets.rows.title), Col("Priority", tickets.rows.priority)])

The user sees a form and a table with the current tickets. The user types a title, picks a priority, and clicks "Create". The renderer calls create_ticket, then list_tickets, and the new ticket appears in the table. The form clears. If create_ticket fails, an error callout appears above the table.

When to use it

Use queries and mutations when:

  • The UI shows data that lives in your systems, such as tickets, orders, or metrics.
  • The data changes after the response, and the UI should show the latest rows.
  • The user creates, updates, or deletes records from the UI.

Do not use them when:

  • The data is small and fixed when the model answers. The model can write the values into the program.
  • The result needs the model to reason about it. Call the tool on your backend before the model answers, or use @ToAssistant.

On this page