Implementing Custom Components

Provide your own components for the C1 API to render

Introduction

Custom components provide a flexible and highly customizable way to introduce your own React components for the C1 API to use in its responses. Custom components unlock a lot of tailor-made interfaces that your application might require, and it can now work within C1.

Package	Minimum version
@crayonai/react-ui	0.8.31
@thesysai/genui-sdk	0.6.34
C1-Version	v-20250915

To illustrate the usefulness of custom components, imagine a flight booking service uses the C1 API to enable generative UI for its users. The user has asked for LOS to JFK flights on September 23, 2025. With the existing C1 components, the information is presented to the user in a C1 Form for selection.

With custom React components, the application can customize how the flight list looks, and have internal states for flight cards and functionality that they want to enable for the user, such as API fetching, interactions, among others.

Integrate Custom Components

The following is a step-by-step guide on how to plug in your React components, along with instructions for C1 to use them in its generations.

For a working example, kindly visit Thesys C1 examples on github

1. Define your React components

   Use @thesysai/genui-sdk’s useOnAction to get an onAction callback. This callback is used to handle user interactions with components. In addition to onAction, each component can have its own internal functions for useC1State management, API fetching, etc.

   Use useC1State to maintain per-response state of the component within C1.

   Refer to Custom Components Specification below for more details.

   src/app/components.tsx

   import { useOnAction, useC1State } from "@thesysai/genui-sdk";
   
   export const FlightList = ({ flights }: { flights: Flight[] }) => {
     const onAction = useOnAction();
   
     // State management to manage component's internal state
     const { getValue, setValue } = useC1State("FlightList")
   
     return (
       <div>
         <h3>Available Flights</h3>
         ...
         {flights.map((flight) => (
           <FlightCard
             // onSelect trigger for the FlightCard
             onSelect={() =>
               onAction(
                 "Select Flight", // Human-friendly message
                 `User selected flight ${flight.flightNumber}` // LLM-specific message with user context
               )
             }
             ...
           />
         ))}
       </div>
     );
   };
   
2. Define the component prop schema

   In order to inform C1 about the expected props for your component, start by defining a Zod-based schema.

   src/app/api/chat/route.ts

   import { z } from "zod";
   
   // Schema of a flight
   const flightSchema = z
     .object({
       flightNumber: z.string(),
       departure: z.string(),
       arrival: z.string(),
       layover: z.string().optional(),
       ...
     })
     .describe(
       "Represents a single flight option including schedule, price, and stops."
     );
   
   // Schema of the flight list component props
   const FlightListSchema = z
     .object({
       flights: z.array(flightSchema),
     })
     // Always include descriptive text for the LLM to understand the component
     .describe(
       "Displays a list of available flights. Renders rich cards with airline, route, times, stops, and price. Includes a clear 'Select' action for each item."
     );
   
3. Pass the schema to the C1 API

   Using the schema described above, convert them as JSON schemas and send it as a part of your C1 API payload.

   Since we used the name FlightList for the React component in the frontend, the CUSTOM_COMPONENT_SCHEMAS must have the same key, FlightList.

   src/app/api/chat/route.ts

   TypeScript

   // Schema to be passed to the C1 API
   const CUSTOM_COMPONENT_SCHEMAS = {
     FlightList: zodToJsonSchema(FlightListSchema),
     ... // other custom components
   };
   
   export async function POST(req: NextRequest) {
     ...
     const client = new OpenAI({
       baseURL: "https://api.thesys.dev/v1/embed/",
       apiKey: process.env.THESYS_API_KEY,
     });
   
     const llmStream = client.chat.completions.runTools({
       ...
       model: "c1/anthropic/claude-sonnet-4/v-20250915",
       // Pass custom component schema
       metadata: {
         thesys: JSON.stringify({
           c1_custom_components: CUSTOM_COMPONENT_SCHEMAS,
         }),
       },
     });
   
     ...
   }
   
4. Pass the React components to GenUI SDK for rendering

   Custom React components can be used by the <C1Chat> and <C1Component> components.

   C1Chat

   src/app/page.tsx

   import { C1Chat } from "@thesysai/genui-sdk";
   import { FlightList } from "./components";
   
   export default function Home() {
     return (
       <C1Chat
         apiUrl="/api/chat"
         customizeC1={{
           customComponents: { FlightList },
         }}
       />
     );
   }
   

   C1Component

   ...
   import { C1Component } from "@thesysai/genui-sdk";
   import { FlightList } from "./components";
   
   <C1Component
     customComponents={{ FlightList }}
     ...
   />;
   

Custom Component Specification

useOnAction

Returns a callback to record a user action with both a user-facing label and an LLM-oriented description.

Returns

callback · (humanFriendlyMessage: string, llmFriendlyMessage: string) => void

Callback to dispatch the action.

Callback Arguments

humanFriendlyMessage · string · required

Visible to the user; concise, human-readable label for the action. Used to give feedback to the user about their action.

Eg: When submitting a form for a trip planner, the human-friendly message can be “Submit response”.

llmFriendlyMessage · string · required

Sent to the LLM; richer context describing what happened. Used to send the contents of the user action to the LLM.

Eg: When submitting a form for a trip planner, the LLM-friendly message can be “User selected ${form.destination}, from ${form.startDate} to ${form.endDate}”.

Refer to Interactivity for more details on onAction, and how human-friendly and llm-friendly messages work.

useC1State

Access a named piece of component state with getter and setter helpers.

Arguments

name · string · required

The state field key you wish to read/write.

Returns

getValue · () => any

Function that returns the current state for the given name.

setValue · (value: any) => void

Updates the field and triggers any save/persist callbacks.