Component Library

Using the built-in library

Out of the box, OpenUI Cloud ships a general-purpose chat library with text, headers, tables, charts, forms, tabs, buttons, and more.

Use it with AgentInterface on the client:

import { chatLibrary } from "@openuidev/thesys";

<AgentInterface llm={llm} componentLibrary={chatLibrary} />;

On the backend, generateSystemPrompt() uses the built-in library by default. Use the embedClient from the API overview; the placement of the generated instructions depends on the API:

import { generateSystemPrompt } from "@openuidev/thesys-server";

const response = await embedClient.responses.create({
  model: "openai/gpt-5",
  input: "Show revenue by region as an interactive dashboard.",
  instructions: generateSystemPrompt({
    instructions: "Optional instructions for the model.",
  }),
});

import { generateSystemPrompt } from "@openuidev/thesys-server";

const completion = await embedClient.chat.completions.create({
  model: "openai/gpt-5",
  messages: [
    {
      role: "system",
      content: generateSystemPrompt({
        instructions: "Optional instructions for the model.",
      }),
    },
    { role: "user", content: "Show revenue by region as an interactive dashboard." },
  ],
});

OpenUI Cloud takes care of everything in between: the system prompt, output validation, and automatic repair all target the built-in library.

Using your own library

Use your own library when the domain calls for components the generic set cannot express or when the application follows its own design system.

Define the library. Create one defineComponent per component in the frontend where your React components live. Prop schemas and descriptions are what the model sees; id is an optional free-form revision tag.

src/lib/chat-library.tsx

import { Metric, Panel } from "@/components";
import { createLibrary, defineComponent } from "@openuidev/react-lang";
import { z } from "zod/v4";

const MetricDef = defineComponent({
  name: "Metric",
  description: "A single KPI stat with an optional trend arrow.",
  props: z.object({
    label: z.string(),
    value: z.string(),
    trend: z.enum(["up", "down"]).optional(),
  }),
  component: ({ props }) => <Metric {...props} />,
});

const PanelDef = defineComponent({
  name: "Panel",
  description: "Top-level container. Children stack vertically.",
  props: z.object({ children: z.array(MetricDef.ref) }),
  component: ({ props, renderNode }) => <Panel>{renderNode(props.children)}</Panel>,
});

export const myLibrary = createLibrary({
  id: "acme-chat@1",
  root: "Panel",
  components: [PanelDef, MetricDef],
});

Generate the spec handover file. openui generate turns the library module into a self-contained JSON file for the backend:

pnpx @openuidev/cli@latest generate --spec src/lib/chat-library.tsx --out ./generated/library-spec.json

Declare it in the backend call. Import the generated JSON and pass it as library.

+ import librarySpec from "./generated/library-spec.json";

  const response = await embedClient.responses.create({
    model: "openai/gpt-5",
    input,
    instructions: generateSystemPrompt({
      instructions: "Optional instructions for the model.",
+     library: librarySpec,
+     promptOptions: { preamble: "You build dashboards for Acme operators." },
    }),
  });

+ import librarySpec from "./generated/library-spec.json";

  const completion = await embedClient.chat.completions.create({
    model: "openai/gpt-5",
    messages: [
      {
        role: "system",
        content: generateSystemPrompt({
          instructions: "Optional instructions for the model.",
+         library: librarySpec,
+         promptOptions: { preamble: "You build dashboards for Acme operators." },
        }),
      },
      ...messages,
    ],
  });

promptOptions is valid only alongside library. Use preamble, additionalRules, and examples to tune the generated prompt.

Swap the client library:

- import { chatLibrary } from "@openuidev/thesys";
+ import { myLibrary } from "@/lib/chat-library";

- <AgentInterface llm={llm} componentLibrary={chatLibrary} />;
+ <AgentInterface llm={llm} componentLibrary={myLibrary} />;

Using the built-in library

Using your own library

On this page