OpenUI

Incremental Editing

Edit an existing UI by sending only what changed. The model writes a patch, mergeStatements merges it by name.

Incremental editing lets the model change an existing UI without writing it again. The model writes only the statements that changed or are new. Your app merges them into the previous program by statement name.

For example, a user has a ticket dashboard and says "add a pie chart". The model does not regenerate the whole dashboard. It writes two lines: a new root that includes the chart, and the chart itself. The queries, state, and table from the first response stay as they were.

Merging a patch by statement nameThe previous program has root, header, tickets, and tbl. The model's patch redefines root to include chart and adds chart. mergeStatements merges them by name: root is replaced, header, tickets, and tbl are kept, and chart is added.Previous programroot = Stack([header, tbl])header = CardHeader("Tickets")tickets = Query(...)tbl = Table([...])Model patchroot = Stack([header, chart, tbl])chart = PieChart(...)mergeStatementsMergesby nameMerged programroot = Stack([header, chart, tbl])Replacedheader = CardHeader("Tickets")Kepttickets = Query(...)Kepttbl = Table([...])Keptchart = PieChart(...)Added

How it works

First response. The model writes the full program:

root = Stack([header, tbl])
header = CardHeader("Tickets")
tickets = Query("list_tickets", {}, {rows: []})
tbl = Table([Col("Title", tickets.rows.title), Col("Status", tickets.rows.status)])

The user says: "add a pie chart showing ticket status breakdown"

The model writes only the patch:

root = Stack([header, chart, tbl])
chart = PieChart(["Open", "Closed"], [@Count(@Filter(tickets.rows, "status", "==", "open")), @Count(@Filter(tickets.rows, "status", "==", "closed"))], "donut")

mergeStatements merges by statement name:

  • root is in the patch, so the new definition replaces the old one. It now includes chart.
  • chart is new, so it is added.
  • header, tickets, and tbl are not in the patch, so they are kept.

Merge rules

  • Same name: the patch definition replaces the old one.
  • New name: the statement is added to the program.
  • Not in the patch: the statement is kept.
  • Removed from its parent: when the model writes the parent again without a child, the child is no longer reachable from root and is dropped. $variables are always kept.
  • name = null: the statement is deleted.

Why use it

  • Fewer tokens. The model writes 2 or 3 lines instead of the whole program.
  • Faster. There is less to stream and less to parse.
  • State stays. Existing queries, $variables, and bindings are not rebuilt.

For example, a dashboard of 20 statements might take about 400 tokens and 2 seconds to stream in full. A patch of 2 statements might take about 60 tokens and 0.3 seconds. The real numbers depend on the program and the model.

Enabling edit mode

Two prompt options control this behavior. Pass them to generateSystemPrompt in your backend:

import { generateSystemPrompt, type LibrarySpec } from "@openuidev/lang-core";
import librarySpec from "./generated/system-prompt.spec.json";

const systemPrompt = generateSystemPrompt({
  library: librarySpec as LibrarySpec,
  promptOptions: {
    editMode: true, // the model writes patches instead of full programs
    inlineMode: true, // the model can mix text and code in one response
  },
});

editMode tells the model to write only the statements that changed or were added. Without it, the model writes the whole program on every turn, even for small changes.

inlineMode lets the model answer with text next to the code. The parser reads code from ```openui-lang fences and treats everything else as text. The model can say "I added a pie chart for the status breakdown" before the patch, so the user knows what changed.

Gateway builds its own prompt and drops editMode and inlineMode. Build the prompt in your backend to use edit mode. See System Prompts.

Complete example

Your backend builds the prompt with editMode: true as shown above and sends the full conversation, including the previous program, with each request. Your app keeps the current program and merges each new response into it:

"use client";

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

export function Dashboard({
  previous,
  latest,
  isStreaming,
}: {
  previous: string; // the program shown before this turn
  latest: string; // the model's patch for this turn
  isStreaming: boolean;
}) {
  const program = isStreaming ? previous : mergeStatements(previous, latest);
  return <Renderer library={openuiLibrary} response={program} isStreaming={isStreaming} />;
}

The component merges after the stream ends. While the patch streams, root is half written, and mergeStatements would drop the statements it cannot reach yet. After the merge, store program as the new previous for the next turn.

The model writes the two-line patch from How it works. The user keeps seeing the same ticket table while the patch streams. When it ends, a donut chart appears between the header and the table, and the table keeps its data. The list_tickets query is not rebuilt.

When to use it

Use incremental editing when:

  • Users refine a generated UI over several turns: "add a filter", "rename the title", "remove the chart".
  • Programs are long, so writing them again costs time and tokens.

Do not use it when:

  • Each response is a new, unrelated UI, such as a chat that answers with a fresh card every turn.
  • Your app does not keep the previous program. Without it, there is nothing to merge into.

On this page