useComponent
Register a React component as a frontend tool renderer in chat
Overview
useComponent is a convenience hook built on top of useFrontendTool.
It registers a tool and renders a React component in chat using the tool call parameters.
This is part of the v2 tool rendering hook set with useRenderTool, useDefaultRenderTool, and useRenderToolCall.
Use this when you want a visual component renderer without writing a full frontend tool config manually.
Signature
import type { StandardSchemaV1 } from "@copilotkit/shared";
import type { ComponentType } from "react";
import { useComponent } from "@copilotkit/react-core/v2";
function useComponent<TSchema extends StandardSchemaV1<any, Record<string, unknown>> | undefined = undefined>(
config: {
name: string;
description?: string;
parameters?: TSchema;
// When parameters is provided, props are inferred from the schema.
// When omitted, render accepts any props.
render: ComponentType<InferRenderProps<TSchema>>;
agentId?: string;
followUp?: boolean;
},
deps?: ReadonlyArray<unknown>,
): void;Parameters
config.name: tool name used by the agent to invoke this component tool.config.description: optional extra description for model guidance.config.parameters: optional Standard Schema (for example Zod, Valibot, or ArkType) for the tool's parameters. When provided,renderprops are inferred from the schema. When omitted, the tool is advertised with an empty parameter schema ({ "type": "object", "properties": {} }), so the agent invokes it with no arguments.config.render: React component rendered with the tool call's arguments as props. While the call streams, the props are the partially parsed JSON of the arguments, not a schema-parsed result, so fields can be missing (see Behavior). Accepts any props whenparametersis omitted.config.agentId: optional agent scope for the registration.config.followUp: whether the agent should continue after rendering the component. Defaults totrue; set it tofalseto stop after the tool call.deps: optional dependency array for refreshing registration.
Behavior
- Prepends a default instruction to the description: "Use this tool to display the "<name>" component in the chat...".
- Calls
useFrontendToolinternally with a render function that spreads the tool parameters as component props. - Props arrive partial while the tool call streams. The component renders as soon as the agent starts the tool call, and again as each argument streams in. Until the call completes, any field can be missing. The props are the arguments the agent sent, not a parsed schema result, so schema defaults such as
.default("c")are not filled in. Therendertype shows the complete parameters, so TypeScript does not warn you. Treat every prop as optional in the component and render a placeholder for missing fields. - Inherits
useFrontendToollifecycle behavior: duplicate-name override warning, tool removal on unmount, and renderer retention for chat history. - Tracks updates by
config.nameplusdeps(include any changing captured values indeps). depscomparison:- Plain data (strings, numbers, booleans,
null, dates, and plain objects and arrays of those): compared by value. An inline literal such as[{ status }]re-registers only when its contents change. - Functions: never count as changed. Keep a changing callback in a ref.
- Class instances and other objects: compared by identity. A circular value such as the
agentfromuseAgentis safe to pass. - Adding or removing an entry: counts as a change.
- Plain data (strings, numbers, booleans,
Usage
const weatherCardSchema = z.object({
city: z.string().describe("City name"),
unit: z.enum(["c", "f"]).default("c"),
});
type WeatherCardProps = z.infer<typeof weatherCardSchema>;
// Props are partial while the tool call streams, so read each field as optional.
function WeatherCard({ city, unit }: Partial<WeatherCardProps>) {
return (
<div className="rounded border p-3">
<div className="text-sm text-zinc-500">Weather request</div>
<div className="font-medium">
{city ?? "…"} ({(unit ?? "c").toUpperCase()})
</div>
</div>
);
}
function App() {
useComponent(
{
name: "showWeatherCard",
description: "Render a weather card in chat for the requested city.",
parameters: weatherCardSchema,
render: WeatherCard,
},
[],
);
return null;
}How is this guide?