useComponent

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 { z } from "zod";
import type { ComponentType } from "react";
import { useComponent } from "@copilotkit/react-core/v2";

function useComponent<TSchema extends z.ZodTypeAny | undefined = undefined>(
  config: {
    name: string;
    description?: string;
    parameters?: TSchema;
    // When parameters is provided, props are inferred via z.infer.
    // When omitted, render accepts any props.
    render: ComponentType<InferRenderProps<TSchema>>;
    agentId?: string;
  },
  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 Zod schema for typed/validated parameters. When provided, render props are inferred from the schema.
• config.render: React component rendered with parsed tool parameters. Accepts any props when parameters is omitted.
• config.agentId: optional agent scope for the registration.
• 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 useFrontendTool internally with a render function that spreads the tool parameters as component props.
• Inherits useFrontendTool lifecycle behavior: duplicate-name override warning, tool removal on unmount, and renderer retention for chat history.
• Tracks updates by config.name plus deps (include any changing captured values in deps).

Usage

const weatherCardSchema = z.object({
  city: z.string().describe("City name"),
  unit: z.enum(["c", "f"]).default("c"),
});

type WeatherCardProps = z.infer<typeof weatherCardSchema>;

function WeatherCard({ city, unit }: WeatherCardProps) {
  return (
    <div className="rounded border p-3">
      <div className="text-sm text-zinc-500">Weather request</div>
      <div className="font-medium">
        {city} ({unit.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;
}

Related

• useFrontendTool
• useRenderTool