Skip to content

The Open Standard for Generative UI

Zk/improve readme (#288)

Zahle Khan0a17e79ed516
diff --git a/README.md b/README.md
index 306ab3f34..09386da03 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,35 @@
-# OpenUI
+<div align="center">
-[Docs](https://openui.com) · [Example App](./examples/openui-chat) · [Discord](https://discord.com/invite/Pbv5PsqUSv) · [Contributing](./CONTRIBUTING.md) · [License](./LICENSE)
+<img src="./assets/banner.png" alt="OpenUI — The Open Standard for Generative UI" width="100%">
-Build **LLM-powered user interfaces** with OpenUI Lang, streaming rendering, and generative UI.
+# OpenUI — The Open Standard for Generative UI
+
+[![Build](https://github.com/thesysdev/openui/actions/workflows/build-js.yml/badge.svg)](https://github.com/thesysdev/openui/actions/workflows/build-js.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Chat-7289da?logo=discord&logoColor=white)](https://discord.com/invite/Pbv5PsqUSv)
+
+</div>
+
+
+OpenUI is a full-stack Generative UI framework — a compact streaming-first language, a React runtime with built-in component libraries, and ready-to-use chat interfaces — that is up to 67% more token-efficient than JSON.
-OpenUI gives you a fast path from model output to structured, streamable UI in React.
-<!-- Hero image placeholder -->
-<!-- [![OpenUI Hero](./docs/static/readme/hero.png)](https://openui.com) -->
+
+---
+
+
+
+[Docs](https://openui.com) · [Playground](https://www.openui.com/playground) · [Sample Chat App](./examples/openui-chat) · [Discord](https://discord.com/invite/Pbv5PsqUSv) · [Contributing](./CONTRIBUTING.md) · [Code of Conduct](./CODE_OF_CONDUCT.md) · [Security](./SECURITY.md) · [License](./LICENSE)
+
---
## What is OpenUI
-OpenUI is an open source toolkit for building AI-native product interfaces in React.
+<div align="center">
+
+<img src="./assets/demo.gif" alt="OpenUI Demo" width="100%">
+</div>
At the center of OpenUI is **OpenUI Lang**: a compact, streaming-first language for model-generated UI. Instead of treating model output as only text, OpenUI lets you define components, generate prompt instructions from that component library, and render structured UI as the model streams.
@@ -26,9 +42,6 @@ At the center of OpenUI is **OpenUI Lang**: a compact, streaming-first language
- **Chat and app surfaces** - Use the same foundation for assistants, copilots, and broader interactive product flows.
-<!-- Product overview video placeholder -->
-<!-- https://openui.com/assets/readme/overview-demo.mp4 -->
-
## Quick Start
```bash
@@ -47,25 +60,28 @@ What this gives you:
- **Streaming support** - Update the UI progressively as output arrives.
- **Working app foundation** - Start from a ready-to-run example instead of wiring everything manually.
-[Detailed docs at openui.com ->](https://openui.com)
-<!-- Quick start demo placeholder -->
-<!-- ![Quick Start Demo](./docs/static/readme/quick-start.gif) -->
## How it works
-OpenUI turns your component library into a contract the model can target.
+Your components define what the model can generate.
+
+```mermaid
+flowchart LR
+ A["Component Library"] --> B["System Prompt"]
+ B --> C["LLM"]
+ C --> D["OpenUI Lang Stream"]
+ D --> E["Renderer"]
+ E --> F["Live UI"]
+```
1. Define or reuse a component library.
2. Generate a system prompt from that library.
3. Send that prompt to your model.
4. Stream OpenUI Lang output back to the client.
-5. Render the structured output progressively with `<Renderer />`.
+5. Render the output progressively with Renderer.
-This creates a direct path from model output to UI without relying on brittle text parsing or ad hoc JSON rendering layers.
-
-<!-- Architecture diagram placeholder -->
-<!-- ![OpenUI Architecture](./docs/static/readme/architecture.png) -->
+Try it yourself in the [Playground](https://www.openui.com/playground) — generate UI live with the default component library.
## Packages
@@ -85,26 +101,45 @@ npm install @openuidev/react-lang @openuidev/react-ui
OpenUI Lang is designed for model-generated UI that needs to be both structured and streamable.
- **Streaming output** — Emit UI incrementally as tokens arrive.
-- **Token efficiency** — Up to 67% fewer tokens than equivalent JSON.
+- **Token efficiency** — Up to 67% fewer tokens than equivalent JSON (see [benchmarks](./benchmarks)).
- **Controlled rendering** — Restrict output to the components you define and register.
- **Typed component contracts** — Define component props and structure up front with Zod schemas.
-## Built for real product surfaces
+### Token efficiency benchmarks
+
+Measured with `tiktoken` (GPT-5 encoder). OpenUI Lang vs two JSON-based streaming formats across seven UI scenarios:
-OpenUI is intended for more than demo chat windows. Use it to build:
+| Scenario | Vercel JSON-Render | Thesys C1 JSON | OpenUI Lang | vs Vercel | vs C1 |
+| ------------------ | -----------------: | -------------: | ----------: | ---------: | ---------: |
+| simple-table | 340 | 357 | 148 | -56.5% | -58.5% |
+| chart-with-data | 520 | 516 | 231 | -55.6% | -55.2% |
+| contact-form | 893 | 849 | 294 | -67.1% | -65.4% |
+| dashboard | 2247 | 2261 | 1226 | -45.4% | -45.8% |
+| pricing-page | 2487 | 2379 | 1195 | -52.0% | -49.8% |
+| settings-panel | 1244 | 1205 | 540 | -56.6% | -55.2% |
+| e-commerce-product | 2449 | 2381 | 1166 | -52.4% | -51.0% |
+| **TOTAL** | **10180** | **9948** | **4800** | **-52.8%** | **-51.7%** |
-- Assistants that render forms, charts, tables, and actions
-- Embedded copilots inside existing products
-- Full-page AI workflows
-- Custom applications backed by your own model APIs
+Full methodology and reproduction steps in [`benchmarks/`](./benchmarks).
## Documentation
Detailed documentation is available at [openui.com](https://openui.com).
-## Explore the repo
+## Repository structure
-This repository contains the OpenUI monorepo, including the implementation, example app, and documentation source.
+```
+openui/
+├── packages/
+│ ├── react-lang/ # Core runtime (parser, renderer, prompt generation)
+│ ├── react-headless/ # Headless chat state & streaming adapters
+│ ├── react-ui/ # Prebuilt chat layouts & component libraries
+│ └── openui-cli/ # CLI for scaffolding & prompt generation
+├── examples/
+│ └── openui-chat/ # Full working example app (Next.js)
+├── docs/ # Documentation site (openui.com)
+└── benchmarks/ # Token efficiency benchmarks
+```
Good places to start:
@@ -112,6 +147,12 @@ Good places to start:
- [`examples/openui-chat`](./examples/openui-chat) for a working app
- [`CONTRIBUTING.md`](./CONTRIBUTING.md) if you want to contribute
+## Community
+
+- [Discord](https://discord.com/invite/Pbv5PsqUSv) — Ask questions, share what you're building
+- [GitHub Issues](https://github.com/thesysdev/openui/issues) — Report bugs or request features
+
+
## Contributing
Contributions are welcome. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for contribution guidelines and ways to get involved.
diff --git a/assets/banner.png b/assets/banner.png
new file mode 100644
index 000000000..403742411
Binary files /dev/null and b/assets/banner.png differ
diff --git a/assets/demo.gif b/assets/demo.gif
new file mode 100644
index 000000000..fe873352e
Binary files /dev/null and b/assets/demo.gif differ
diff --git a/package.json b/package.json
index 63a88636d..1c7221c29 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "OpenUI",
"version": "1.0.0",
- "description": "Monorepo for OpenUI's JavaScript packages. See https://openui.com for more information.",
+ "description": "The open standard for generative UI — a streaming-first language, React runtime, and component libraries for building AI-powered chat and copilot interfaces",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
@@ -19,7 +19,26 @@
"prettier-plugin-organize-imports": "^3.2.4",
"typescript": "^5.9.3"
},
- "keywords": [],
+ "keywords": [
+ "openui",
+ "generative-ui",
+ "react",
+ "ai",
+ "llm",
+ "streaming",
+ "chat",
+ "copilot",
+ "components",
+ "ui-framework"
+ ],
+ "homepage": "https://openui.com",
"author": "[email protected]",
- "license": "MIT"
+ "license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/thesysdev/openui.git"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
+ }
}
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index 88a5271fb..64af1cfd4 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -1,6 +1,9 @@
-# OpenUI CLI
+# @openuidev/cli
-The OpenUI CLI helps you get started with OpenUI faster.
+Command-line tool for [OpenUI](https://openui.com) — scaffold AI-powered generative UI chat apps and generate LLM system prompts from your React component libraries.
+
+[![npm](https://img.shields.io/npm/v/@openuidev/cli)](https://www.npmjs.com/package/@openuidev/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/thesysdev/openui/blob/main/LICENSE)
It currently supports two workflows:
@@ -148,3 +151,11 @@ node dist/index.js generate --help
- interactive prompts can be cancelled without creating output
- `create` requires the template files to be present in the built package
- `generate` exits with a non-zero code if the file is missing or no valid library export is found
+
+## Documentation
+
+Full documentation and guides are available at **[openui.com](https://openui.com)**.
+
+## License
+
+[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
diff --git a/packages/openui-cli/package.json b/packages/openui-cli/package.json
index 5f5f84ebe..ec8026150 100644
--- a/packages/openui-cli/package.json
+++ b/packages/openui-cli/package.json
@@ -1,7 +1,7 @@
{
"name": "@openuidev/cli",
"version": "0.0.3",
- "description": "CLI for OpenUI",
+ "description": "CLI for OpenUI — scaffold generative UI chat apps and generate LLM system prompts from component libraries",
"bin": {
"openui": "dist/index.js"
},
@@ -23,9 +23,30 @@
"devDependencies": {
"@types/node": "^22.15.32"
},
- "keywords": [],
+ "keywords": [
+ "openui",
+ "cli",
+ "scaffolding",
+ "generative-ui",
+ "ai",
+ "llm",
+ "system-prompt",
+ "nextjs",
+ "react",
+ "chatbot",
+ "code-generator"
+ ],
+ "homepage": "https://openui.com",
"author": "[email protected]",
"license": "MIT",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/thesysdev/openui.git",
+ "directory": "packages/openui-cli"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
+ },
"dependencies": {
"@inquirer/core": "^11.1.5",
"@inquirer/prompts": "^8.3.0",
diff --git a/packages/react-headless/README.md b/packages/react-headless/README.md
index 749a699a4..8087da67c 100644
--- a/packages/react-headless/README.md
+++ b/packages/react-headless/README.md
@@ -1,13 +1,270 @@
# @openuidev/react-headless
-Headless React primitives, streaming adapters, and state management for OpenUI.
+Headless React primitives for [OpenUI](https://openui.com) — chat state management, streaming adapters, and message format converters. Build any chat UI while OpenUI handles the streaming, threading, and state.
+
+[![npm](https://img.shields.io/npm/v/@openuidev/react-headless)](https://www.npmjs.com/package/@openuidev/react-headless)
+[![npm downloads](https://img.shields.io/npm/dm/@openuidev/react-headless)](https://www.npmjs.com/package/@openuidev/react-headless)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/thesysdev/openui/blob/main/LICENSE)
## Install
```bash
+npm install @openuidev/react-headless
+# or
pnpm add @openuidev/react-headless
```
-## Docs
+**Peer dependencies:** `react >=19.0.0`, `react-dom >=19.0.0`, `zustand ^4.5.5`
+
+## Overview
+
+`@openuidev/react-headless` gives you everything needed to build a chat experience without imposing any UI. It provides:
+
+- **`ChatProvider`** — A React context provider that manages threads, messages, and streaming state via a Zustand store.
+- **Selector hooks** — `useThread()` and `useThreadList()` to read and interact with chat state.
+- **Streaming adapters** — Parse SSE or SDK responses from OpenAI, AG-UI, or custom backends.
+- **Message formats** — Convert between your API's message format and the internal AG-UI format.
+
+## Quick Start
+
+### URL-based setup
+
+The simplest configuration — point to your API and the provider handles REST calls and streaming automatically:
+
+```tsx
+import { ChatProvider } from "@openuidev/react-headless";
+
+function App() {
+ return (
+ <ChatProvider
+ apiUrl="/api/chat"
+ threadApiUrl="/api/threads"
+ >
+ <YourChatUI />
+ </ChatProvider>
+ );
+}
+```
+
+### Custom functions
+
+For full control, provide your own functions instead of URLs:
+
+```tsx
+<ChatProvider
+ processMessage={async ({ threadId, messages, abortController }) => {
+ return fetch("/api/chat", {
+ method: "POST",
+ body: JSON.stringify({ threadId, messages }),
+ signal: abortController.signal,
+ });
+ }}
+ fetchThreadList={async () => {
+ const res = await fetch("/api/threads");
+ return res.json();
+ }}
+ createThread={async (firstMessage) => {
+ const res = await fetch("/api/threads", {
+ method: "POST",
+ body: JSON.stringify({ message: firstMessage }),
+ });
+ return res.json();
+ }}
+>
+ <YourChatUI />
+</ChatProvider>
+```
+
+## Hooks
+
+### `useThread()`
+
+Access the current thread's messages, send new messages, and check streaming state:
+
+```tsx
+import { useThread } from "@openuidev/react-headless";
+
+function ChatMessages() {
+ const { messages, isRunning, processMessage, cancelMessage } = useThread();
+
+ const handleSend = (text: string) => {
+ processMessage({ role: "user", content: text });
+ };
+
+ return (
+ <div>
+ {messages.map((msg) => (
+ <div key={msg.id}>{msg.content}</div>
+ ))}
+ {isRunning && <button onClick={cancelMessage}>Stop</button>}
+ </div>
+ );
+}
+```
+
+**Returns:** `ThreadState & ThreadActions`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `messages` | `Message[]` | Messages in the current thread |
+| `isRunning` | `boolean` | Whether the model is currently streaming |
+| `isLoadingMessages` | `boolean` | Whether messages are being fetched |
+| `threadError` | `Error \| null` | Error from the last operation |
+| `processMessage(msg)` | `(msg) => Promise<void>` | Send a message and stream the response |
+| `cancelMessage()` | `() => void` | Abort the current stream |
+| `appendMessages(...msgs)` | `(...msgs) => void` | Append messages locally |
+| `updateMessage(msg)` | `(msg) => void` | Update a message in place |
+| `deleteMessage(id)` | `(id) => void` | Remove a message |
+| `setMessages(msgs)` | `(msgs) => void` | Replace all messages |
+
+### `useThreadList()`
+
+Manage multiple conversation threads:
+
+```tsx
+import { useThreadList } from "@openuidev/react-headless";
+
+function ThreadSidebar() {
+ const { threads, selectedThreadId, selectThread, switchToNewThread, deleteThread } =
+ useThreadList();
+
+ return (
+ <nav>
+ <button onClick={switchToNewThread}>New Chat</button>
+ {threads.map((t) => (
+ <div key={t.id} onClick={() => selectThread(t.id)}>
+ {t.title}
+ <button onClick={() => deleteThread(t.id)}>Delete</button>
+ </div>
+ ))}
+ </nav>
+ );
+}
+```
+
+**Returns:** `ThreadListState & ThreadListActions`
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `threads` | `Thread[]` | All loaded threads |
+| `selectedThreadId` | `string \| null` | Currently selected thread |
+| `isLoadingThreads` | `boolean` | Whether the thread list is loading |
+| `hasMoreThreads` | `boolean` | Whether more threads can be loaded |
+| `loadThreads()` | `() => void` | Fetch the thread list |
+| `loadMoreThreads()` | `() => void` | Load the next page of threads |
+| `selectThread(id)` | `(id) => void` | Select a thread |
+| `switchToNewThread()` | `() => void` | Deselect and start a new conversation |
+| `createThread(msg)` | `(msg) => Promise<Thread>` | Create a thread with a first message |
+| `updateThread(thread)` | `(thread) => void` | Update thread metadata |
+| `deleteThread(id)` | `(id) => void` | Delete a thread |
+
+### `useMessage()`
+
+Access the current message inside a message component:
+
+```tsx
+import { useMessage } from "@openuidev/react-headless";
+
+function MessageBubble() {
+ const { message } = useMessage();
+ return <div className="bubble">{message.content}</div>;
+}
+```
+
+## Streaming Adapters
+
+Adapters transform HTTP responses into the internal event stream. Pass one to `ChatProvider` via `streamProtocol`:
+
+```tsx
+import { ChatProvider, openAIAdapter } from "@openuidev/react-headless";
+
+<ChatProvider apiUrl="/api/chat" streamProtocol={openAIAdapter}>
+ {children}
+</ChatProvider>
+```
+
+| Adapter | Description |
+| :--- | :--- |
+| `agUIAdapter` | Default — parses AG-UI SSE events (`data: {json}\n`) |
+| `openAIAdapter` | Parses OpenAI Chat Completions streaming (`ChatCompletionChunk`) |
+| `openAIResponsesAdapter` | Parses OpenAI Responses API streaming (`ResponseStreamEvent`) |
+| `openAIReadableStreamAdapter` | Parses OpenAI SDK's `Stream.toReadableStream()` NDJSON output |
+
+### Custom adapter
+
+Implement the `StreamProtocolAdapter` interface:
+
+```ts
+import type { StreamProtocolAdapter, AGUIEvent } from "@openuidev/react-headless";
+
+const myAdapter: StreamProtocolAdapter = {
+ async *parse(response: Response): AsyncIterable<AGUIEvent> {
+ // parse the response stream and yield AGUIEvent objects
+ },
+};
+```
+
+## Message Formats
+
+Message formats convert between your API's message shape and the internal AG-UI format. Pass one to `ChatProvider` via `messageFormat`:
+
+```tsx
+import { ChatProvider, openAIMessageFormat } from "@openuidev/react-headless";
+
+<ChatProvider apiUrl="/api/chat" messageFormat={openAIMessageFormat}>
+ {children}
+</ChatProvider>
+```
+
+| Format | Description |
+| :--- | :--- |
+| `identityMessageFormat` | Default — no conversion (messages are already AG-UI format) |
+| `openAIMessageFormat` | Converts to/from OpenAI `ChatCompletionMessageParam[]` |
+| `openAIConversationMessageFormat` | Converts to/from OpenAI Responses API `ResponseInputItem[]` |
+
+### Custom format
+
+Implement the `MessageFormat` interface:
+
+```ts
+import type { MessageFormat } from "@openuidev/react-headless";
+
+const myFormat: MessageFormat = {
+ toApi: (messages) => messages.map(convertToMyFormat),
+ fromApi: (data) => data as Message[],
+};
+```
+
+## Types
+
+```ts
+import type {
+ ChatProviderProps,
+ ChatStore,
+ Thread,
+ ThreadState,
+ ThreadActions,
+ ThreadListState,
+ ThreadListActions,
+ CreateMessage,
+ Message,
+ UserMessage,
+ AssistantMessage,
+ SystemMessage,
+ ToolMessage,
+ ToolCall,
+ FunctionCall,
+ MessageFormat,
+ StreamProtocolAdapter,
+ AGUIEvent,
+ EventType,
+} from "@openuidev/react-headless";
+```
+
+## Documentation
+
+Full documentation and guides are available at **[openui.com](https://openui.com)**.
+
+## License
-Detailed documentation is available at [openui.com](https://openui.com).
+[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
diff --git a/packages/react-headless/package.json b/packages/react-headless/package.json
index 4380941fd..13e9e1ab2 100644
--- a/packages/react-headless/package.json
+++ b/packages/react-headless/package.json
@@ -1,7 +1,7 @@
{
"name": "@openuidev/react-headless",
"version": "0.7.8",
- "description": "Generative UI SDK",
+ "description": "Headless React primitives for AI chat — state management, streaming adapters for OpenAI and AG-UI, message format converters, and thread management for OpenUI generative UI apps",
"license": "MIT",
"main": "dist/index.js",
"types": "dist/index.d.ts",
@@ -32,17 +32,31 @@
"keywords": [
"openui",
"react",
- "core",
- "generative",
+ "headless",
+ "chat",
+ "streaming",
"ai",
+ "generative-ui",
+ "llm",
+ "openai",
+ "zustand",
+ "state-management",
+ "sse",
+ "server-sent-events",
+ "chatbot",
+ "copilot",
"agentic",
- "framework"
+ "ag-ui"
],
+ "homepage": "https://openui.com",
"author": "[email protected]",
"repository": {
"type": "git",
"url": "https://github.com/thesysdev/openui.git",
- "directory": "js/packages/react-headless"
+ "directory": "packages/react-headless"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
},
"dependencies": {
"@ag-ui/core": "^0.0.45"
diff --git a/packages/react-lang/README.md b/packages/react-lang/README.md
index 15f9dc74d..b1dcd3d86 100644
--- a/packages/react-lang/README.md
+++ b/packages/react-lang/README.md
@@ -1,13 +1,180 @@
# @openuidev/react-lang
-React renderer for OpenUI Lang.
+Core runtime for [OpenUI](https://openui.com) — define component libraries, generate model prompts, and render structured UI from streaming LLM output.
+
+[![npm](https://img.shields.io/npm/v/@openuidev/react-lang)](https://www.npmjs.com/package/@openuidev/react-lang)
+[![npm downloads](https://img.shields.io/npm/dm/@openuidev/react-lang)](https://www.npmjs.com/package/@openuidev/react-lang)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/thesysdev/openui/blob/main/LICENSE)
## Install
```bash
+npm install @openuidev/react-lang
+# or
pnpm add @openuidev/react-lang
```
-## Docs
+**Peer dependencies:** `react >=19.0.0`
+
+## Overview
+
+`@openuidev/react-lang` provides three core capabilities:
+
+1. **Define components** — Use `defineComponent` and `createLibrary` to declare what the model is allowed to generate, with typed props via Zod schemas.
+2. **Generate prompts** — Call `library.prompt()` to produce a system prompt that instructs the model how to emit OpenUI Lang output.
+3. **Render output** — Use `<Renderer>` to parse and progressively render streamed OpenUI Lang into React components.
+
+## Quick Start
+
+### 1. Define a component
+
+```tsx
+import { defineComponent } from "@openuidev/react-lang";
+import { z } from "zod";
+
+const Greeting = defineComponent({
+ name: "Greeting",
+ description: "Displays a greeting message",
+ props: z.object({
+ name: z.string().describe("The person's name"),
+ mood: z.enum(["happy", "excited"]).optional().describe("Tone of the greeting"),
+ }),
+ component: ({ name, mood }) => (
+ <div className={mood === "excited" ? "text-xl font-bold" : ""}>
+ Hello, {name}!
+ </div>
+ ),
+});
+```
+
+### 2. Create a library
+
+```ts
+import { createLibrary } from "@openuidev/react-lang";
+
+const library = createLibrary({
+ components: [Greeting, Card, Table /* ... */],
+ root: "Card", // optional default root component
+});
+```
+
+### 3. Generate a system prompt
+
+```ts
+const systemPrompt = library.prompt({
+ preamble: "You are a helpful assistant.",
+ additionalRules: ["Always greet the user by name."],
+ examples: ["<Greeting name='Alice' mood='happy' />"],
+});
+```
+
+### 4. Render streamed output
+
+```tsx
+import { Renderer } from "@openuidev/react-lang";
+
+function AssistantMessage({ response, isStreaming }) {
+ return (
+ <Renderer
+ response={response}
+ library={library}
+ isStreaming={isStreaming}
+ onAction={(event) => console.log("Action:", event)}
+ />
+ );
+}
+```
+
+## API Reference
+
+### Component Definition
+
+| Export | Description |
+| :--- | :--- |
+| `defineComponent(config)` | Define a single component with a name, Zod props schema, description, and React renderer |
+| `createLibrary(definition)` | Create a library from an array of defined components |
+
+### Rendering
+
+| Export | Description |
+| :--- | :--- |
+| `Renderer` | React component that parses and renders OpenUI Lang output |
+
+**`RendererProps`:**
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `response` | `string \| null` | Raw OpenUI Lang text from the model |
+| `library` | `Library` | Component library from `createLibrary()` |
+| `isStreaming` | `boolean` | Whether the model is still streaming (disables form interactions) |
+| `onAction` | `(event: ActionEvent) => void` | Callback when a component triggers an action |
+| `onStateUpdate` | `(state: Record<string, any>) => void` | Callback when form field values change |
+| `initialState` | `Record<string, any>` | Initial form state for hydration |
+| `onParseResult` | `(result: ParseResult \| null) => void` | Callback when the parse result changes |
+
+### Parser (Server-Side)
+
+| Export | Description |
+| :--- | :--- |
+| `createParser(library)` | Create a one-shot parser for complete OpenUI Lang text |
+| `createStreamingParser(library)` | Create an incremental parser for streaming input |
+
+### Context Hooks
+
+Use these inside component renderers to interact with the rendering context:
+
+| Hook | Description |
+| :--- | :--- |
+| `useIsStreaming()` | Whether the model is still streaming |
+| `useRenderNode()` | Render child element nodes |
+| `useTriggerAction()` | Trigger an action event |
+| `useGetFieldValue()` | Get a form field's current value |
+| `useSetFieldValue()` | Set a form field's value |
+| `useSetDefaultValue()` | Set a field's default value |
+| `useFormName()` | Get the current form's name |
+
+### Form Validation
+
+| Export | Description |
+| :--- | :--- |
+| `useFormValidation()` | Access form validation state |
+| `useCreateFormValidation()` | Create a form validation context |
+| `validate(value, rules)` | Run validation rules against a value |
+| `builtInValidators` | Built-in validators (required, email, min, max, etc.) |
+
+### Types
+
+```ts
+import type {
+ Library,
+ LibraryDefinition,
+ DefinedComponent,
+ ComponentRenderer,
+ ComponentRenderProps,
+ ComponentGroup,
+ PromptOptions,
+ RendererProps,
+ ActionEvent,
+ ElementNode,
+ ParseResult,
+ LibraryJSONSchema,
+} from "@openuidev/react-lang";
+```
+
+## JSON Schema Output
+
+Libraries can also produce a JSON Schema representation of their components:
+
+```ts
+const schema = library.toJSONSchema();
+// schema.$defs["Card"] → { properties: {...}, required: [...] }
+// schema.$defs["Greeting"] → { properties: {...}, required: [...] }
+```
+
+## Documentation
+
+Full documentation, guides, and the language specification are available at **[openui.com](https://openui.com)**.
+
+## License
-Detailed documentation is available at [openui.com](https://openui.com).
+[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
diff --git a/packages/react-lang/package.json b/packages/react-lang/package.json
index c9d0685ac..2115e893b 100644
--- a/packages/react-lang/package.json
+++ b/packages/react-lang/package.json
@@ -1,7 +1,7 @@
{
"name": "@openuidev/react-lang",
"version": "0.1.2",
- "description": "OpenUI-lang renderer and standard library for React",
+ "description": "Define component libraries, generate LLM system prompts, and render streaming OpenUI Lang output in React — the core runtime for OpenUI generative UI",
"license": "MIT",
"type": "module",
"main": "dist/index.js",
@@ -26,6 +26,32 @@
"prepare": "pnpm run build",
"ci": "pnpm run lint:check && pnpm run format:check"
},
+ "keywords": [
+ "openui",
+ "generative-ui",
+ "react",
+ "llm",
+ "streaming",
+ "renderer",
+ "parser",
+ "ai",
+ "components",
+ "prompt-generation",
+ "zod",
+ "ui-generation",
+ "model-driven-ui",
+ "openui-lang"
+ ],
+ "homepage": "https://openui.com",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/thesysdev/openui.git",
+ "directory": "packages/react-lang"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
+ },
+ "author": "[email protected]",
"dependencies": {
"zod": "^4.0.0"
},
diff --git a/packages/react-ui/README.md b/packages/react-ui/README.md
index 0866c7dcf..f14dd553d 100644
--- a/packages/react-ui/README.md
+++ b/packages/react-ui/README.md
@@ -1,13 +1,183 @@
# @openuidev/react-ui
-React UI components and default libraries for OpenUI.
+React UI components, chat layouts, and component libraries for [OpenUI](https://openui.com). Drop-in chat surfaces with theming, or use individual components in your own layout.
+
+[![npm](https://img.shields.io/npm/v/@openuidev/react-ui)](https://www.npmjs.com/package/@openuidev/react-ui)
+[![npm downloads](https://img.shields.io/npm/dm/@openuidev/react-ui)](https://www.npmjs.com/package/@openuidev/react-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/thesysdev/openui/blob/main/LICENSE)
## Install
```bash
-pnpm add @openuidev/react-ui
+npm install @openuidev/react-ui @openuidev/react-lang @openuidev/react-headless
+# or
+pnpm add @openuidev/react-ui @openuidev/react-lang @openuidev/react-headless
+```
+
+**Peer dependencies:** `react >=19.0.0`, `react-dom >=19.0.0`, `zustand ^4.5.5`, `@openuidev/react-lang`, `@openuidev/react-headless`
+
+Don't forget to import the component styles:
+
+```ts
+import "@openuidev/react-ui/components.css";
+```
+
+## Overview
+
+This package provides three layers:
+
+1. **Chat layouts** — Ready-to-use chat surfaces (`FullScreen`, `Copilot`, `BottomTray`) that wire up the provider, streaming, and rendering automatically.
+2. **Component library** — A built-in set of UI components (charts, tables, forms, cards, etc.) that models can generate via OpenUI Lang.
+3. **Individual components** — Use `Button`, `Card`, `Table`, `Charts`, and 30+ components directly in your own UI.
+
+## Quick Start
+
+The fastest way to get a working chat app:
+
+```tsx
+import { FullScreen } from "@openuidev/react-ui";
+import "@openuidev/react-ui/components.css";
+
+function App() {
+ return (
+ <FullScreen
+ apiUrl="/api/chat"
+ threadApiUrl="/api/threads"
+ />
+ );
+}
+```
+
+### Chat Layouts
+
+| Component | Description |
+| :--- | :--- |
+| `FullScreen` | Full-page chat with a thread sidebar |
+| `Copilot` | Side-panel copilot overlay |
+| `BottomTray` | Collapsible bottom tray chat |
+
+All chat layouts accept `apiUrl`, `threadApiUrl`, and theming props. See the [chat docs](https://openui.com/docs/chat) for full configuration.
+
+### Copilot example
+
+```tsx
+import { Copilot } from "@openuidev/react-ui";
+
+function App() {
+ return (
+ <div>
+ <main>Your app content</main>
+ <Copilot apiUrl="/api/chat" threadApiUrl="/api/threads" />
+ </div>
+ );
+}
+```
+
+## Built-in Component Libraries
+
+The package ships with two preconfigured OpenUI Lang libraries:
+
+| Export | Description |
+| :--- | :--- |
+| `openuiLibrary` | Full component library — charts, tables, forms, cards, images, and more |
+| `openuiChatLibrary` | Chat-optimized subset with follow-ups, steps, and callouts |
+
+Use them directly when building custom chat experiences:
+
+```tsx
+import { Renderer } from "@openuidev/react-lang";
+import { openuiLibrary } from "@openuidev/react-ui";
+
+function AssistantMessage({ content, isStreaming }) {
+ return (
+ <Renderer
+ response={content}
+ library={openuiLibrary}
+ isStreaming={isStreaming}
+ />
+ );
+}
```
-## Docs
+Generate a system prompt from the library:
+
+```ts
+import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui";
+
+const systemPrompt = openuiLibrary.prompt(openuiPromptOptions);
+```
+
+## Theming
+
+Wrap your app in `ThemeProvider` to customize colors, typography, spacing, and effects:
+
+```tsx
+import { ThemeProvider, createTheme } from "@openuidev/react-ui";
+
+const customTheme = createTheme({
+ primary: "#6366f1",
+ background: "#fafafa",
+ foreground: "#1a1a1a",
+});
+
+function App() {
+ return (
+ <ThemeProvider mode="light" lightTheme={customTheme}>
+ <YourApp />
+ </ThemeProvider>
+ );
+}
+```
+
+| Export | Description |
+| :--- | :--- |
+| `ThemeProvider` | Context provider for theming |
+| `createTheme(overrides)` | Create a theme with validation and defaults |
+| `defaultLightTheme` | Built-in light theme |
+| `defaultDarkTheme` | Built-in dark theme |
+| `swatchTokens` | Token palette for use in theme builders |
+
+## Components
+
+All components are available as individual imports:
+
+| Category | Components |
+| :--- | :--- |
+| **Layout** | `Card`, `CardHeader`, `SectionBlock`, `Tabs`, `Accordion`, `Carousel`, `Separator`, `Steps` |
+| **Data Display** | `Table`, `Charts` (bar, line, area, pie, radar, scatter), `ListBlock`, `ListItem`, `Tag`, `TagBlock`, `CodeBlock`, `Image`, `ImageBlock`, `ImageGallery` |
+| **Forms** | `Input`, `TextArea`, `Select`, `CheckBoxGroup`, `CheckBoxItem`, `RadioGroup`, `RadioItem`, `SwitchGroup`, `SwitchItem`, `Slider`, `DatePicker`, `FormControl`, `Label` |
+| **Actions** | `Button`, `Buttons`, `IconButton`, `FollowUpBlock`, `FollowUpItem` |
+| **Feedback** | `Callout`, `TextCallout`, `MessageLoading` |
+| **Content** | `TextContent`, `MarkDownRenderer` |
+| **Chat** | `FullScreen`, `Copilot`, `BottomTray`, `Shell.*`, `CopilotShell.*`, `ToolCall`, `ToolResult` |
+
+### Per-component imports
+
+For smaller bundles, import components individually:
+
+```ts
+import { Button } from "@openuidev/react-ui/Button";
+import { Card } from "@openuidev/react-ui/Card";
+import { Charts } from "@openuidev/react-ui/Charts";
+```
+
+## Subpath Exports
+
+| Import path | Description |
+| :--- | :--- |
+| `@openuidev/react-ui` | All components and libraries |
+| `@openuidev/react-ui/components.css` | Compiled component styles |
+| `@openuidev/react-ui/genui-lib` | OpenUI Lang libraries and prompt options |
+| `@openuidev/react-ui/tailwind` | Tailwind CSS plugin |
+| `@openuidev/react-ui/styles/*` | SCSS utilities |
+| `@openuidev/react-ui/scssUtils` | SCSS utility functions |
+| `@openuidev/react-ui/<Component>` | Per-component entry points |
+
+## Documentation
+
+Full documentation, component guides, and live examples are available at **[openui.com](https://openui.com)**.
+
+
+## License
-Detailed documentation is available at [openui.com](https://openui.com).
+[MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
diff --git a/packages/react-ui/package.json b/packages/react-ui/package.json
index 91b941646..131fc09de 100644
--- a/packages/react-ui/package.json
+++ b/packages/react-ui/package.json
@@ -141,16 +141,32 @@
"react",
"ui",
"components",
- "generative",
+ "generative-ui",
"ai",
- "agentic",
- "framework"
+ "chat",
+ "chatbot",
+ "copilot",
+ "charts",
+ "forms",
+ "tables",
+ "theming",
+ "design-system",
+ "llm",
+ "streaming",
+ "tailwind",
+ "radix",
+ "recharts",
+ "markdown"
],
+ "homepage": "https://openui.com",
"author": "[email protected]",
"repository": {
"type": "git",
"url": "https://github.com/thesysdev/openui.git",
- "directory": "js/packages/react-ui"
+ "directory": "packages/react-ui"
+ },
+ "bugs": {
+ "url": "https://github.com/thesysdev/openui/issues"
},
"eslintConfig": {
"extends": [