The Open Standard for Generative UI
OpenUI Overview
1.0
The OpenUI specification is three documents:
- overview.md (this file): what OpenUI is, and a short tour of every feature with an example.
- language.md: the exact rules of the language, for people who build parsers and renderers.
- prompt.md: the LibrarySpec, the system prompt, and the message protocol.
Three roles appear throughout. The model writes OpenUI Lang. The client parses and renders it (in React, the Renderer). The host is your app around the client: it calls the model, provides tools, and stores messages.
What's new in 1.0
1.0 makes OpenUI ready for production and for other implementations:
- Conformance fixtures. Plain-text cases with expected JSON results, so a client in any language can check that it parses, streams, evaluates, and runs actions the same way (
fixtures/1.0/). - Message protocol. One format for streamed and stored responses (section 4).
- Stored UIs keep working. Backward-compatibility rules for libraries (section 3).
- Custom functions and actions. A library adds its own
@functions, like@Percent(section 2.11), and its own actions, which the host handles. - Extending a library.
library.extend()derives a library with components added, replaced, or removed (prompt.md, section 2.8). - Small conveniences. One action needs no
Action([...])wrapper, and any value as@ToAssistantcontext.
1. Introduction
1.1 What OpenUI is
OpenUI Lang is a compact, line-oriented language that a model writes to describe a user interface. It replaces JSON trees and raw HTML with a short program, one statement per line. The client renders the program while it streams in:
root = Card([header, chart])
header = Header("Monthly Revenue", "Last 6 months")
chart = BarChart(labels, [series])
labels = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
series = Series("Revenue", [12000, 15000, 14000, 18000, 21000, 25000])
Every line binds a name to a value. A name can be used before it is defined. The first line gives the shape of the page, and each later line fills it in.
Quickstart
// Server: send this as the system prompt.
import { generateSystemPrompt } from "@openuidev/lang-core";
import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui";
const systemPrompt = generateSystemPrompt({
library: openuiLibrary.toSpec(),
promptOptions: openuiPromptOptions,
});
// Client: render the model's text while it streams.
import { Renderer } from "@openuidev/react-lang";
<Renderer library={openuiLibrary} response={text} isStreaming={isStreaming} />
The full walkthrough is the docs quickstart.
1.2 Design goals
- Few tokens. Positional arguments and short names keep programs small, up to 67% smaller than the same UI in JSON.
- Streams by default. Every partial program is a valid page, so the UI builds up as the model writes.
- Forgiving. A mistake removes the smallest broken piece. The rest of the page still renders.
- Interactive without the model. State, expressions, and actions run in the client, with no round trip to the model.
1.3 The end-to-end flow
flowchart LR
user([User]) -- "What did I spend last month?" --> app[Your app]
app -- "system prompt from your library + message" --> llm["Model (any provider)"]
llm -- "openui-lang stream" --> app
app --> ren[OpenUI renderer]
ren -- "live UI, streamed" --> user
ren -- "queries and mutations" --> tools[Your data and tools]
tools -- "live data" --> ren
Your app holds the data and the component library. The library generates a system prompt that teaches the model the language and your components. The model streams OpenUI Lang back, and the renderer draws it as it arrives. The page talks to your data through queries and mutations.
A turn looks like this:
sequenceDiagram
participant App as Your app
participant Model
participant Renderer as OpenUI renderer
participant User
App->>Model: system prompt (generated from your library) + user message
Model->>App: openui-lang, streamed token by token
App->>Renderer: the streamed text
Renderer->>User: page builds up as tokens arrive
Note over App: stores the message (content, context, end)
User->>App: action event (click, form submit, @ToAssistant)
alt chat app
App->>Model: follow-up with context and form state, ]]>openui: lines stripped
Model->>Renderer: a new response, rendered as a new message
else editing surface (canvas, dashboard, artifact)
App->>Model: current program + the request
Model->>Renderer: incremental edit: only the changed statements
end
The app wraps each response in ]]>openui: lines and stores it that way (section 4). The model never sees those lines. In a chat app, a click becomes a new turn and the model answers with a new message. In an editing surface, the model answers with only the changed statements, and the host merges them into the current program (section 2.6).
2. Features
Component names in the examples are examples only: every library defines its own.
2.1 Components
The model builds UI from components you define. Arguments are positional, in the order the library lists the props. Say Button lists label, action, variant:
btn = Button("Save changes", saveAction, "primary")
The renderer receives { label: "Save changes", action: saveAction, variant: "primary" }. Optional arguments at the end can be left out. null skips an optional argument in the middle.
Rendering starts at the statement named root. Everything it reaches renders. A statement nothing reaches is not rendered.
This statement is the entry. If there is no root, the first value statement (never a $ declaration) whose value calls the library's root component is the entry, with a warning. Each library names its root component in its LibrarySpec. If root exists but is not a component, or there is no entry, nothing renders and the client reports no-root when the stream ends. Rules in language.md, section 2.2.
2.2 References and hoisting
A statement can use any other statement by name, wherever it appears:
root = Card([title, kpis, refreshBtn])
title = Header("Support Overview")
kpis = Stack([openCount, closedCount])
openCount = Metric("Open", 12)
closedCount = Metric("Closed", 8)
refreshBtn = Button("Refresh")
The first line uses title, kpis, and refreshBtn before they exist. It lets the model write the layout first and the data last.
A name with no statement yet is unresolved. That means "not yet", not "error": the Stack shows one metric until closedCount arrives. When two statements bind the same name, the later one wins. Rules in language.md, sections 2.3 and 2.4.
2.3 Streaming
The client parses and renders again on every chunk, so a half-received response is always a valid page:
| Arrived so far | On screen |
|---|---|
root = Card([header, chart]) |
An empty card. |
header = Header("Monthly Rev |
A header reading "Monthly Rev", filling in as the model types. |
enue", "Last 6 months") |
The full header. |
chart = BarChart(labels, [series]) |
An empty chart. |
labels = [...], series = Series(...) |
The bars fill in. |
The parser closes open brackets and strings for you, so root = Card([header already renders an empty card. When the stream ends, the result is the same as parsing the full text at once. The host tells the client when the stream ends (in React, isStreaming turns false). Rules in language.md, section 4.
2.4 Actions
An action runs when the user clicks. A button can send a message back to the model or open a link:
askBtn = Button("Explain this chart", @ToAssistant("Explain the revenue chart"))
docsBtn = Button("Docs", @OpenUrl("https://example.com/docs"))
@ToAssistant takes an optional second argument, context. It can be any value, and the host receives it unchanged:
approveBtn = Button("Approve", @ToAssistant("Approve this order", { orderId: 42 }))
For more than one action, wrap them in Action([...]). They run in order:
closeBtn = Button("Close ticket", Action([@Run(save), @Set($showModal, false), @ToAssistant("Ticket closed")]))
There are five built-in actions: @ToAssistant, @OpenUrl, @Set and @Reset (for state, section 2.9), and @Run (for queries and mutations, section 2.10). A library can add its own actions, such as @CopyToClipboard(text), which the host receives as events. A failed mutation stops the actions after it. Rules in language.md, section 6.3.
2.5 Forms and validation
Inputs carry validation rules as an object:
email = Input("email", "[email protected]", "email", { required: true, email: true })
The renderer checks the rules, shows the messages, and blocks submit until they pass. The rules are required, email, url, numeric, minLength, maxLength, min, max, and pattern.
Inputs inside a form submit together. The form keeps each value under the input's name:
contactForm = Form("contact", Buttons([submitBtn]), [nameField, emailField])
nameField = FormControl("Name", Input("name", "Your name", "text", { required: true }))
emailField = FormControl("Email", Input("email", "[email protected]", "email", { required: true, email: true }))
submitBtn = Button("Submit")
When a button sends a message, the form values go with it. Rules in language.md, sections 5.3 and 5.4.
2.6 Incremental editing
To change a page, the model sends a patch: only the statements that change. The host merges it into the previous program by name once the patch has finished streaming (in React, with mergeStatements). Merging earlier would drop statements a half-written root cannot reach yet. The page showing:
root = Card([header, chart])
header = Header("Monthly Revenue", "Last 6 months")
chart = BarChart(labels, [series])
labels = ["Jan", "Feb", "Mar", "Apr", "May", "Jun"]
series = Series("Revenue", [12000, 15000, 14000, 18000, 21000, 25000])
The user says "show it weekly". The model answers:
header = Header("Weekly Revenue", "Last 4 weeks")
chart = BarChart(weekLabels, [series])
weekLabels = ["W1", "W2", "W3", "W4"]
series = Series("Revenue", [4800, 5300, 5100, 6200])
Named statements are replaced, new ones are added, and root stays. Nothing uses labels any more, so it is removed. chart = null would delete the chart. Rules in language.md, section 7.
2.7 Expressions
The language has arithmetic, comparison, logic, ? :, member access, and indexing. The client evaluates them, so derived values update without the model:
status = TextContent(total > 100000 ? "On track" : "Behind target")
share = @Round(part / total * 100, 1)
Member access on a list gives that field of every element: if sales.rows is a list of objects, sales.rows.amount is the list of their amounts. Rules in language.md, sections 1.5, 3.2, and 3.3.
2.8 Built-in functions
Built-ins start with @:
- Aggregation:
@Count,@Sum,@Avg,@Min,@Max,@First,@Last. - Reshaping:
@Filter,@Sort. - Math:
@Round,@Abs,@Floor,@Ceil. - Iteration:
@Each.
Calls nest, so a filtered, sorted list takes two lines and goes straight into a component:
urgent = @Filter(tickets.rows, "priority", "==", "high")
newest = @Sort(urgent, "createdAt", "desc")
rows = @Each(newest, "t", Row(t.title, Tag(t.priority)))
@Each(list, name, template) builds the template once per element, with name bound to that element. Every built-in is defined in language.md, sections 3.4 and 3.5.
2.9 Reactive state
Variables that start with $ hold state the user or an action changes: values bound to inputs, and values changed by @Set or @Reset. They tie components together: one component writes $query, others read it:
$query = ""
search = Input("search", "Search tickets", "text", null, $query)
label = TextContent("Searching for " + $query)
Passing $query to an input binds it both ways. Typing updates $query, and everything that reads it updates too.
$tab = "overview"
picker = Select("tab", [SelectItem("overview", "Overview"), SelectItem("billing", "Billing")], null, null, $tab)
body = $tab == "overview" ? overviewPanel : billingPanel
$ marks what the user or an action can write. Reactivity is not limited to $: any statement that reads a $ variable or a query result updates when that input changes. Tool data and derived values use plain names: tickets = Query(...), openCount = @Count(tickets.rows). A $ variable with no declaration starts as null. Rules in language.md, section 5.
2.10 Queries and mutations
Query reads data from a tool your app provides. Mutation writes it. The model writes which tool to call. The host provides the tools:
$days = "7"
data = Query("analytics", { days: $days }, { rows: [] })
filter = Select("days", [SelectItem("7", "7 days"), SelectItem("30", "30 days")], null, null, $days)
The arguments are the tool name, its arguments, and a default shown while loading. A $variable written directly in the arguments makes the query fetch again when it changes. A $variable reached only through another statement does not. An optional fourth argument refreshes on a timer in seconds.
A mutation runs only when an action runs it:
createResult = Mutation("create_ticket", { title: $title })
submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title)]))
A mutation result has status (idle, loading, success, error), data, and error, so the page can show progress. Name queries without $: tickets = Query(...). $tickets = Query(...) still runs the query, but $tickets in an expression reads the state store, not the result. Rules in language.md, section 6.
2.11 Custom functions
A library can add its own functions. The model calls them like built-ins:
share = TextContent(@Percent(done, total))
The library declares each one with defineFunction({ name, description, params, returns, fn }). The program passes arguments by position, like components, and fn receives them as one object keyed by the params names. The prompt always lists custom functions. The implementation (fn) stays in the host's library and runs in the client, never in the prompt. Functions are pure and synchronous: same inputs, same output, no side effects. A call to an unknown @ name evaluates to null and reports unknown-function. Rules in language.md, section 3.6, and prompt.md, section 2.5.
2.12 Error recovery
Models make mistakes, so the client removes the smallest broken piece and renders the rest. It reports each problem with the statement, the problem, and a hint:
{ "source": "parser", "code": "unknown-component", "statementId": "chart",
"message": "Unknown component PieChart", "hint": "Available components: BarChart, LineChart, Table" }
Send the error back to the model, and it can answer with a one-line fix through incremental editing. The full error table is in language.md, section 8.2.
3. Keeping stored UIs working
A stored program has no prop names. A stored call like Button("Save", saveAction, "primary") is only correct while label, action, variant is still the prop order. Three rules keep stored programs rendering as a library changes:
- Add props only at the end of a component's prop list.
- Never reorder or remove a prop. Leave an unused prop in place and ignore it.
- A new required prop needs a default, because stored calls do not pass it.
Built-in names are reserved, so a library never uses a name like @Count. A library can have an id and a version. They are metadata and do not change parsing. The same rules for library authors are in prompt.md, section 3.2.
4. Streaming and storing responses
A response travels and is stored as plain text. The host wraps the program in a few lines of its own, each starting with ]]>openui::
]]>openui:content?library=support%401.2.0
root = Card([header, chart])
header = Header("Monthly Revenue", "Last 6 months")
]]>openui:context
{"formState": {"days": "30"}, "context": {"orderId": 42}}
]]>openui:end
contentholds the program (or prose).contextholds JSON the host keeps with the message, such as form values and click data. The host defines its shape.endsays the stream finished. A stored message without it was cut off. It still renders as far as it got.
The same format works while streaming and in storage. The model never writes or sees these lines: the host strips them before it sends history to the model. The client accepts text with or without them and ignores them when rendering. prompt.md, section 6.3, gives the reference format for turning a click into the next user turn.
The renderer still holds live state while the page is open. The context section is how that state is saved: when a stored message is loaded again, the host reads context and gives the form values back to the renderer. The full protocol is in prompt.md, section 7.