Skip to content

The Open Standard for Generative UI

feat(react-ui): add card and form components to openuiLibrary (#1182)

abhithesysb4aa87cb2d0b
diff --git a/.changeset/react-ui-base-library-components.md b/.changeset/react-ui-base-library-components.md
new file mode 100644
index 000000000..e369d7e58
--- /dev/null
+++ b/.changeset/react-ui-base-library-components.md
@@ -0,0 +1,9 @@
+---
+"@openuidev/react-ui": minor
+---
+
+Add the new card and form components to `openuiLibrary` (the base, non-chat library), so they're available outside `AgentInterface` too: `InlineHeader`, `EditableTable`, `Chips`/`ChipItem`, `OptionCards`/`OptionCard`, `IconButton`, `EntityList`, `Text`/`BoldText`, `IconText`/`ImageText`/`ImageTextLarge`, `MetricIndicatorInline`/`MetricIndicatorWithStrikethrough`, and the `Snippet`/`Overview`/`Context`/`Composite`/`Visual` card blocks with their items.
+
+`FormControl` now accepts `Chips` and `OptionCards` inputs in both libraries, which let the chat library drop its `ChatForm`/`ChatFormControl` duplicates and register the base `Form`/`FormControl` directly.
+
+Fixes `IconButton`, which was registered but unreachable in the chat library (no union pointed at it) — it can now be placed as a `Card`/`Stack` child in both libraries.
diff --git a/packages/react-ui/src/genui-lib/FormControl/schema.ts b/packages/react-ui/src/genui-lib/FormControl/schema.ts
index 9cb0a734b..7158168d3 100644
--- a/packages/react-ui/src/genui-lib/FormControl/schema.ts
+++ b/packages/react-ui/src/genui-lib/FormControl/schema.ts
@@ -1,7 +1,9 @@
import { z } from "zod/v4";
import { CheckBoxGroup } from "../CheckBoxGroup";
+import { Chips } from "../Chips";
import { DatePicker } from "../DatePicker";
import { Input } from "../Input";
+import { OptionCards } from "../OptionCards";
import { RadioGroup } from "../RadioGroup";
import { Select } from "../Select";
import { Slider } from "../Slider";
@@ -17,6 +19,8 @@ export const FormControlSchema = z.object({
Slider.ref,
CheckBoxGroup.ref,
RadioGroup.ref,
+ Chips.ref,
+ OptionCards.ref,
]),
hint: z.string().optional(),
});
diff --git a/packages/react-ui/src/genui-lib/openuiChatLibrary.tsx b/packages/react-ui/src/genui-lib/openuiChatLibrary.tsx
index 70fb01311..da3ea85ab 100644
--- a/packages/react-ui/src/genui-lib/openuiChatLibrary.tsx
+++ b/packages/react-ui/src/genui-lib/openuiChatLibrary.tsx
@@ -38,8 +38,8 @@ import {
// Forms
import { CheckBoxGroup, CheckBoxItem } from "./CheckBoxGroup";
import { DatePicker } from "./DatePicker";
-import { Form, FormRenderer } from "./Form";
-import { FormControlRenderer } from "./FormControl";
+import { Form } from "./Form";
+import { FormControl } from "./FormControl";
import { Input } from "./Input";
import { Label } from "./Label";
import { RadioGroup, RadioItem } from "./RadioGroup";
@@ -98,55 +98,14 @@ import { VisualCardBlock, VisualCardItem } from "./VisualCardBlock";
import { ChatContentChildUnion } from "./unions";
-// ── Chat FormControl — same renderer as the base FormControl, wider input union ──
-// (Chips / OptionCards are chat-only inputs, so the base FormControlSchema is left untouched.)
-
-const ChatFormControl = defineComponent({
- name: "FormControl",
- props: z.object({
- label: z.string(),
- input: z.union([
- Input.ref,
- TextArea.ref,
- Select.ref,
- DatePicker.ref,
- Slider.ref,
- CheckBoxGroup.ref,
- RadioGroup.ref,
- Chips.ref,
- OptionCards.ref,
- ]),
- hint: z.string().optional(),
- }),
- description: "Field with label, input component, and optional hint text",
- component: FormControlRenderer,
-});
-
-// ── Chat Form — same renderer, but its fields reference the chat FormControl above ──
-
-const ChatForm = defineComponent({
- name: "Form",
- props: z.object({
- name: z.string(),
- buttons: Buttons.ref,
- fields: z.array(ChatFormControl.ref).default([]),
- }),
- description: "Form container with fields and explicit action buttons",
- component: FormRenderer,
-});
-
// ── Chat containers — same renderers as the base Tabs / Accordion / Carousel / SectionItem,
// but their content unions accept every chat block (card blocks, EntityList, EditableTable,
// InlineHeader, ...). Defined here, not in unions.ts, to avoid circular imports; registered
// under the base names so SectionBlock's `SectionItem.ref` resolves to the chat variant.
// Everything a nested container may hold — no SectionBlock nesting.
-// Base `Form.ref` is swapped for the chat Form so the JSON schema emits a $ref to the
-// registered component instead of inlining the base Form's shape.
const ChatNestedContentUnion = z.union(
- ChatContentChildUnion.options
- .filter((o) => o !== SectionBlock.ref)
- .map((o) => (o === Form.ref ? ChatForm.ref : o)) as [
+ ChatContentChildUnion.options.filter((o) => o !== SectionBlock.ref) as [
z.ZodTypeAny,
z.ZodTypeAny,
...z.ZodTypeAny[],
@@ -463,8 +422,8 @@ export const openuiChatLibrary = createLibrary({
ScatterSeries,
Point,
// Forms
- ChatForm,
- ChatFormControl,
+ Form,
+ FormControl,
Label,
Input,
TextArea,
@@ -501,7 +460,7 @@ export const openuiChatLibrary = createLibrary({
TagBlock,
Tag,
EntityList,
- // Content (chat-only)
+ // Content
InlineHeader,
Icon,
IconButton,
diff --git a/packages/react-ui/src/genui-lib/openuiLibrary.tsx b/packages/react-ui/src/genui-lib/openuiLibrary.tsx
index 79b4c9b2f..c713c9a4b 100644
--- a/packages/react-ui/src/genui-lib/openuiLibrary.tsx
+++ b/packages/react-ui/src/genui-lib/openuiLibrary.tsx
@@ -3,6 +3,33 @@
import type { ComponentGroup } from "@openuidev/react-lang";
import { createLibrary } from "@openuidev/react-lang";
+// Card building blocks
+import { BoldText } from "./BoldText";
+import { EntityList } from "./EntityList";
+import { IconButton } from "./IconButton";
+import { IconText } from "./IconText";
+import { ImageText } from "./ImageText";
+import { ImageTextLarge } from "./ImageTextLarge";
+import { InlineHeader } from "./InlineHeader";
+import { ListBlock } from "./ListBlock";
+import { ListItem } from "./ListItem";
+import { MetricIndicatorInline, MetricIndicatorWithStrikethrough } from "./MetricIndicator";
+import { Text } from "./Text";
+
+// Editable table
+import { EditableTable } from "./EditableTable";
+
+// Selection inputs
+import { ChipItem, Chips } from "./Chips";
+import { OptionCard, OptionCards } from "./OptionCards";
+
+// Card blocks
+import { CompositeCardBlock, CompositeCardItem } from "./CompositeCardBlock";
+import { ContextCardBlock, ContextCardItem } from "./ContextCardBlock";
+import { OverviewCardBlock, OverviewCardItem } from "./OverviewCardBlock";
+import { SnippetCardBlock, SnippetCardItem } from "./SnippetCardBlock";
+import { VisualCardBlock, VisualCardItem } from "./VisualCardBlock";
+
// Content
import { Callout } from "./Callout";
import { Card } from "./Card";
@@ -106,8 +133,10 @@ export const openuiComponentGroups: ComponentGroup[] = [
"ImageBlock",
"ImageGallery",
"CodeBlock",
+ "InlineHeader",
],
notes: [
+ "- InlineHeader is a compact heading + description pair for labelling a block (lighter than CardHeader).",
'- Use Cards to group related KPIs or sections. Stack with direction "row" for side-by-side layouts.',
'- Success toast: Callout("success", "Saved", "Done.", $showSuccess) — use @Set($showSuccess, true) in save action, auto-dismisses after 3s. For errors: result.status == "error" ? Callout("error", "Failed", result.error) : null',
'- KPI card: Card([TextContent("Label", "small"), TextContent("" + @Count(@Filter(data.rows, "field", "==", "value")), "large-heavy")])',
@@ -115,8 +144,10 @@ export const openuiComponentGroups: ComponentGroup[] = [
},
{
name: "Tables",
- components: ["Table", "Col"],
+ components: ["Table", "Col", "EditableTable"],
notes: [
+ "- EditableTable lets the user edit cells inline. Give it a unique name, columns of { type, key, header } with type one of text | number | date-single | select | url (select also needs options: [{ value, label }]).",
+ "- data is an array of { id, values } rows where values are ordered positionally to match columns. Edited data is submitted when the user clicks Save Changes.",
'- Table is COLUMN-oriented: Table([Col("Label", dataArray), Col("Count", countArray, "number")]). Use array pluck for data: data.rows.fieldName',
'- Col data can be component arrays for styled cells: Col("Status", @Each(data.rows, "item", Tag(item.status, null, "sm", item.status == "open" ? "success" : "danger")))',
'- Row actions: Col("Actions", @Each(data.rows, "t", Button("Edit", Action([@Set($showEdit, true), @Set($editId, t.id)]))))',
@@ -174,8 +205,14 @@ export const openuiComponentGroups: ComponentGroup[] = [
"RadioItem",
"SwitchGroup",
"SwitchItem",
+ "Chips",
+ "ChipItem",
+ "OptionCards",
+ "OptionCard",
],
notes: [
+ "- Chips: compact single/multiple selection pills. Use ChipItem references for each option.",
+ "- OptionCards: larger selectable cards with title, subtitle and an optional Icon or Image on top. Use OptionCard references for each option.",
"- For Form fields, define EACH FormControl as its own reference — do NOT inline all controls in one array. This allows progressive field-by-field streaming.",
"- NEVER nest Form inside Form — each Form should be a standalone container.",
"- Form requires explicit buttons. Always pass a Buttons(...) reference as the third Form argument.",
@@ -188,16 +225,50 @@ export const openuiComponentGroups: ComponentGroup[] = [
},
{
name: "Buttons",
- components: ["Button", "Buttons"],
+ components: ["Button", "Buttons", "IconButton"],
notes: [
+ "- Icon renders a lucide icon by kebab-case name; it is also used as the icon of IconButton, IconText and OptionCard.",
'- Toggle in @Each: @Each(rows, "t", Button(t.status == "open" ? "Close" : "Reopen", Action([...])))',
],
},
{
name: "Data Display",
- components: ["TagBlock", "Tag", "Icon"],
+ components: ["TagBlock", "Tag", "Icon", "EntityList", "ListBlock", "ListItem"],
notes: [
'- Color-mapped Tag: Tag(value, null, "sm", value == "high" ? "danger" : value == "medium" ? "warning" : "neutral")',
+ "- EntityList is a compact two-column list of { left, right } rows (e.g. name / value). size='default' also supports a header and footer row; size='small' does not.",
+ "- ListBlock is a numbered or image list of ListItem references. An action on ListItem is optional.",
+ ],
+ },
+ {
+ name: "Cards",
+ components: [
+ "SnippetCardBlock",
+ "SnippetCardItem",
+ "OverviewCardBlock",
+ "OverviewCardItem",
+ "ContextCardBlock",
+ "ContextCardItem",
+ "CompositeCardBlock",
+ "CompositeCardItem",
+ "VisualCardBlock",
+ "VisualCardItem",
+ "Text",
+ "BoldText",
+ "IconText",
+ "ImageText",
+ "ImageTextLarge",
+ "MetricIndicatorInline",
+ "MetricIndicatorWithStrikethrough",
+ ],
+ notes: [
+ "- Card blocks lay out 2+ items in a responsive grid (or carousel where supported). Every item in a block must have the same structure.",
+ "- SnippetCardItem: small card with lhs (IconText | ImageText) and optional rhs (Text | BoldText) — good for key/value facts.",
+ "- OverviewCardItem: small card with top (IconText | ImageText | Text) and optional bottom MetricIndicatorInline — good for KPIs.",
+ "- ContextCardItem: medium card with a title (string or Tag), body text and optional background image — good for summaries.",
+ "- CompositeCardItem: rich card with header, body array (Text, BoldText, MetricIndicatorInline, IconText, Image, charts, ListBlock, TagBlock, EntityList) and footer (price + Button) — good for products/offers.",
+ "- VisualCardItem: image-first card with a BoldText body and optional Tag.",
+ "- Text / BoldText / IconText / ImageText / ImageTextLarge / MetricIndicator* are the inline building blocks used INSIDE card items; do not place them directly in the root Card.",
],
},
];
@@ -222,9 +293,11 @@ export const openuiLibrary = createLibrary({
ImageBlock,
ImageGallery,
CodeBlock,
+ InlineHeader,
// Tables
Table,
Col,
+ EditableTable,
// Charts (2D)
BarChartCondensed,
LineChartCondensed,
@@ -258,9 +331,14 @@ export const openuiLibrary = createLibrary({
RadioItem,
SwitchGroup,
SwitchItem,
+ ChipItem,
+ Chips,
+ OptionCard,
+ OptionCards,
// Buttons
Button,
Buttons,
+ IconButton,
// Layout
Stack,
Tabs,
@@ -275,6 +353,28 @@ export const openuiLibrary = createLibrary({
TagBlock,
Tag,
Icon,
+ EntityList,
+ ListBlock,
+ ListItem,
+ // Card building blocks
+ Text,
+ BoldText,
+ IconText,
+ ImageText,
+ ImageTextLarge,
+ MetricIndicatorInline,
+ MetricIndicatorWithStrikethrough,
+ // Card blocks
+ SnippetCardItem,
+ SnippetCardBlock,
+ OverviewCardItem,
+ OverviewCardBlock,
+ ContextCardItem,
+ ContextCardBlock,
+ CompositeCardItem,
+ CompositeCardBlock,
+ VisualCardItem,
+ VisualCardBlock,
// Modal
Modal,
],
diff --git a/packages/react-ui/src/genui-lib/prompt-options/index.ts b/packages/react-ui/src/genui-lib/prompt-options/index.ts
index d9185bce7..30a76777f 100644
--- a/packages/react-ui/src/genui-lib/prompt-options/index.ts
+++ b/packages/react-ui/src/genui-lib/prompt-options/index.ts
@@ -44,6 +44,68 @@ tabReact = TabItem("react", "React", reactContent)
tabVue = TabItem("vue", "Vue", vueContent)
reactContent = [TextContent("React is a library by Meta for building UIs."), Callout("info", "Note", "React uses JSX syntax.")]
vueContent = [TextContent("Vue is a progressive framework by Evan You."), Callout("success", "Tip", "Vue has a gentle learning curve.")]`,
+
+ `Example 5 — KPI and product cards:
+
+root = Stack([kpiHeader, kpiBlock, productsHeader, productCards])
+kpiHeader = InlineHeader("This Month", "Key account metrics")
+kpiBlock = SnippetCardBlock([kpi1, kpi2, kpi3])
+kpi1 = SnippetCardItem("revenue", kpi1lhs, kpi1rhs)
+kpi1lhs = IconText(kpi1icon, "neutral", "m", "Revenue", "Month to date", false, "horizontal")
+kpi1icon = Icon("circle-dollar-sign", "finance")
+kpi1rhs = BoldText("number", "$48,200", "+8.1%", "metric")
+kpi2 = SnippetCardItem("active-users", kpi2lhs, kpi2rhs)
+kpi2lhs = IconText(kpi2icon, "neutral", "m", "Active Users", "This month", false, "horizontal")
+kpi2icon = Icon("users", "people")
+kpi2rhs = BoldText("number", "1,204", "+3.4%", "metric")
+kpi3 = SnippetCardItem("churn", kpi3lhs, kpi3rhs)
+kpi3lhs = IconText(kpi3icon, "neutral", "m", "Churn", "This month", false, "horizontal")
+kpi3icon = Icon("user-minus", "people")
+kpi3rhs = BoldText("number", "1.8%", "-0.3%", "metric")
+productsHeader = InlineHeader("Top Products", "By units sold")
+productCards = CompositeCardBlock([p1, p2])
+p1 = CompositeCardItem("widget-pro", p1header, [p1body], p1footer)
+p1header = IconText(p1icon, "neutral", "m", "Widget Pro", "Best seller", true, "horizontal")
+p1icon = Icon("package", "shopping")
+p1body = MetricIndicatorInline("2,410 units", "Sold this month", { direction: "up", value: 12 })
+p1footer = { price: BoldText("text", "$29.00"), button: p1btn }
+p1btn = Button("View Details", Action([@ToAssistant("Show details for Widget Pro")]), "secondary")
+p2 = CompositeCardItem("widget-mini", p2header, [p2body], p2footer)
+p2header = IconText(p2icon, "neutral", "m", "Widget Mini", "New arrival", true, "horizontal")
+p2icon = Icon("box", "shopping")
+p2body = MetricIndicatorInline("980 units", "Sold this month", { direction: "up", value: 4 })
+p2footer = { price: BoldText("text", "$14.00"), button: p2btn }
+p2btn = Button("View Details", Action([@ToAssistant("Show details for Widget Mini")]), "secondary")`,
+
+ `Example 6 — Editable table and a selection form:
+
+root = Stack([tableHeader, editTable, formHeader, prefsForm])
+tableHeader = InlineHeader("Team Roster", "Click a cell to edit")
+editTable = EditableTable("roster", [colName, colRole, colStart], [row1, row2])
+colName = { type: "text", key: "name", header: "Name" }
+colRole = { type: "select", key: "role", header: "Role", options: [roleEng, roleDesign] }
+roleEng = { value: "eng", label: "Engineering" }
+roleDesign = { value: "design", label: "Design" }
+colStart = { type: "date-single", key: "start", header: "Start Date" }
+row1 = { id: "1", values: ["Alex Kim", "eng", "2024-01-15"] }
+row2 = { id: "2", values: ["Jamie Lee", "design", "2024-03-02"] }
+formHeader = InlineHeader("Preferences", "Tell us how you like to work")
+prefsForm = Form("prefs", formButtons, [fc1, fc2])
+fc1 = FormControl("Working Style", styleCards, "Pick the one that fits best")
+styleCards = OptionCards("style", "single", [style1, style2])
+style1 = OptionCard("focused", "Deep Focus", "Long uninterrupted blocks", style1icon)
+style1icon = Icon("target", "tools")
+style2 = OptionCard("collab", "Collaborative", "Frequent pairing and syncs", style2icon)
+style2icon = Icon("users", "people")
+fc2 = FormControl("Tools", toolChips, "Select all that apply")
+toolChips = Chips("tools", "multiple", [tool1, tool2, tool3])
+tool1 = ChipItem("figma", "Figma", tool1icon)
+tool1icon = Icon("figma", "design")
+tool2 = ChipItem("slack", "Slack", tool2icon)
+tool2icon = Icon("message-square", "communication")
+tool3 = ChipItem("notion", "Notion", tool3icon)
+tool3icon = Icon("notebook", "text")
+formButtons = Buttons([Button("Save", Action([@ToAssistant("Save preferences")]), "primary")])`,
];
export const openuiAdditionalRules: string[] = [
@@ -56,6 +118,12 @@ export const openuiAdditionalRules: string[] = [
"Multi-query refresh: Action([@Run(mutation), @Run(query1), @Run(query2), @Reset(...)])",
"$variables are reactive: changing via Select or @Set re-evaluates all Queries and expressions referencing them",
"Use existing components (Tabs, Accordion, Modal) before inventing ternary show/hide patterns",
+ "Card blocks (SnippetCardBlock, OverviewCardBlock, ContextCardBlock, CompositeCardBlock, VisualCardBlock) need at least 2 items; every item in a block must have the same structure.",
+ "Text / BoldText / IconText / ImageText / ImageTextLarge / MetricIndicatorInline / MetricIndicatorWithStrikethrough are inline building blocks used INSIDE card items — do not place them directly in a Stack or Card.",
+ "EntityList size='small' (no header/footer) is only for use inside a CompositeCardItem body; use size='default' everywhere else.",
+ "Image URLs must be real (from a tool result or the user) — never invent or template an image URL.",
+ "Always pass a category to Icon — it enables a topical fallback when the exact icon name is unavailable.",
+ "EditableTable requires the consuming app to persist edits — use it only when the user or app explicitly asks for an editable table; default to Table for read-only data.",
];
export const openuiPromptOptions: PromptOptions = {
diff --git a/packages/react-ui/src/genui-lib/unions.ts b/packages/react-ui/src/genui-lib/unions.ts
index 7eab30506..2a159e079 100644
--- a/packages/react-ui/src/genui-lib/unions.ts
+++ b/packages/react-ui/src/genui-lib/unions.ts
@@ -23,6 +23,7 @@ import {
SingleStackedBarChart,
} from "./Charts";
+import { IconButton } from "./IconButton";
import { Table } from "./Table";
import { TagBlock } from "./TagBlock";
@@ -68,11 +69,22 @@ export const ContentChildUnion = z.union([
TagBlock.ref,
Form.ref,
Buttons.ref,
+ IconButton.ref,
Steps.ref,
+ InlineHeader.ref,
+ EntityList.ref,
+ EditableTable.ref,
+ SnippetCardBlock.ref,
+ OverviewCardBlock.ref,
+ ContextCardBlock.ref,
+ CompositeCardBlock.ref,
+ VisualCardBlock.ref,
]);
-// Chat-specific content union — no Stack, adds ListBlock / FollowUpBlock / SectionBlock,
-// plus the chat-only blocks (InlineHeader, EntityList, EditableTable, card blocks).
+// Chat-specific content union — no Stack, adds ListBlock / FollowUpBlock / SectionBlock
+// (conversational features with no place in the base library). Everything else
+// (InlineHeader, EntityList, EditableTable, card blocks) now lives in the base
+// ContentChildUnion above and is inherited here via the spread.
// Note: Tabs and Carousel are NOT included here to avoid circular deps (Tabs/schema.ts imports ContentChildUnion).
// ChatCardChildUnion (which adds Tabs + Carousel) is defined in openuiChatLibrary.tsx.
export const ChatContentChildUnion = z.union([
@@ -80,12 +92,4 @@ export const ChatContentChildUnion = z.union([
ListBlock.ref,
FollowUpBlock.ref,
SectionBlock.ref,
- InlineHeader.ref,
- EntityList.ref,
- EditableTable.ref,
- SnippetCardBlock.ref,
- OverviewCardBlock.ref,
- ContextCardBlock.ref,
- CompositeCardBlock.ref,
- VisualCardBlock.ref,
]);