Components as Tools

Let your agent render your React Native components in the chat by calling them as tools.

What is this?

Tool-based generative UI is the simplest form of generative UI. You register a React Native component with useComponent, and CopilotKit offers it to the agent as a tool. When the agent calls the tool, CopilotKit renders your component in the chat and passes the tool's arguments to it as props.

Unlike tool rendering, which draws UI for a real backend tool, here the tool is the component. There is no handler, no user interaction, and no server-side execution. The agent decides when to show it and fills in the data. CopilotKit renders it.

When should I use this?

Use useComponent when you want to:

  • Display rich UI (cards, charts, lists) in the chat
  • Show structured data the agent has derived from its reasoning
  • Render previews, status indicators, or visual summaries
  • Let the agent present information beyond plain text

For components that need user input, see Human-in-the-loop. For UI around a real backend tool, see Tool Call Rendering.

How it works in code

Install the CopilotKit LangGraph SDK

npm install @copilotkit/sdk-js

Wire CopilotKit state + tools into your graph

Frontend tools registered with useFrontendTool arrive on the agent's state at state.copilotkit.actions. Use CopilotKitStateAnnotation to expose that channel on your graph, then call convertActionsToDynamicStructuredTools(...) inside your chat node to bind the LLM to those actions.

frontend-tools.ts
import type { RunnableConfig } from "@langchain/core/runnables";
import { SystemMessage } from "@langchain/core/messages";
import { MemorySaver, START, StateGraph } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import {
  convertActionsToDynamicStructuredTools,
  CopilotKitStateAnnotation,
} from "@copilotkit/sdk-js/langgraph";

// CopilotKit forwards frontend tools to the agent via
// `state.copilotkit.actions`. `CopilotKitStateAnnotation` adds that
// channel to your graph's state; `convertActionsToDynamicStructuredTools`
// turns the forwarded action schemas into LangChain tools you can bind
// at model-invocation time.
const AgentStateAnnotation = CopilotKitStateAnnotation;
export type AgentState = typeof AgentStateAnnotation.State;

const SYSTEM_PROMPT = "You are a helpful, concise assistant.";

async function runChatNode(
  state: AgentState,
  config: RunnableConfig,
  model: ChatOpenAI,
) {
  const modelWithTools = model.bindTools!([
    ...convertActionsToDynamicStructuredTools(state.copilotkit?.actions ?? []),
  ]);

  const response = await modelWithTools.invoke(
    [new SystemMessage({ content: SYSTEM_PROMPT }), ...state.messages],
    config,
  );

  return { messages: response };
}

async function chatNode(state: AgentState, config: RunnableConfig) {
  return runChatNode(
    state,
    config,
    new ChatOpenAI({
      modelKwargs: { reasoning_effort: "none" },
      temperature: 0,
      model: "gpt-6-luna",
    }),
  );
}

function compileGraph(node: typeof chatNode) {
  return new StateGraph(AgentStateAnnotation)
    .addNode("chat_node", node)
    .addEdge(START, "chat_node")
    .addEdge("chat_node", "__end__")
    .compile({ checkpointer: new MemorySaver() });
}

export const graph = compileGraph(chatNode);

Call a frontend tool from a node with no model

A node does not need a model to call a frontend tool. Return an AIMessage with a tool_calls entry. This example calls the change_background tool that the frontend above registers. When the run ends, CopilotKit runs the matching useFrontendTool handler in the browser. Then it starts a follow-up run with the result as a ToolMessage. Route that run to a node that reads the result, so the graph does not call the tool again:

src/agent.ts
import { randomUUID } from "node:crypto";
import { AIMessage, ToolMessage } from "@langchain/core/messages";
import { END, START, StateGraph } from "@langchain/langgraph";
import { CopilotKitStateAnnotation } from "@copilotkit/sdk-js/langgraph";

type AgentState = typeof CopilotKitStateAnnotation.State;

// Ask the frontend to run `change_background`. No model call.
async function requestBackground(state: AgentState) {
  return {
    messages: [
      new AIMessage({
        content: "",
        tool_calls: [
          {
            id: randomUUID(),
            name: "change_background",
            args: { background: "linear-gradient(135deg, #1e3a8a, #9333ea)" },
            type: "tool_call",
          },
        ],
      }),
    ],
  };
}

// Runs on the follow-up run, after the frontend returns the tool result.
async function confirm(state: AgentState) {
  const result = state.messages.at(-1);
  return {
    messages: [new AIMessage(`The frontend returned: ${result?.content}`)],
  };
}

export const graph = new StateGraph(CopilotKitStateAnnotation)
  .addNode("request_background", requestBackground)
  .addNode("confirm", confirm)
  .addConditionalEdges(START, (state: AgentState) => {
    const last = state.messages.at(-1);
    return last && ToolMessage.isInstance(last)
      ? "confirm"
      : "request_background";
  })
  .addEdge("request_background", END)
  .addEdge("confirm", END)
  .compile();

The tool call must be in the graph state. copilotkitEmitToolCall alone only streams the call. At the end of the run, the messages from the graph state replace the streamed ones, so the handler never runs.

Define your component's props as a zod schema. The schema becomes the tool's parameters, which tell the model which arguments to send. Add zod to your app if it isn't there yet (npm install zod).

src/BarChart.tsx
import { Text, View } from "react-native";
import { z } from "zod";

export const barChartPropsSchema = z.object({
  title: z.string().describe("Chart title"),
  data: z.array(
    z.object({
      label: z.string(),
      value: z.number(),
    }),
  ),
});

type BarChartProps = z.infer<typeof barChartPropsSchema>;

export function BarChart({ title, data }: BarChartProps) {
  // While the agent streams the call, props can be missing or partial.
  const rows = data ?? [];
  const max = Math.max(1, ...rows.map((row) => row.value ?? 0));

  return (
    <View style={{ padding: 12, borderRadius: 12, backgroundColor: "#f4f4f8", gap: 6 }}>
      <Text style={{ fontWeight: "600" }}>{title ?? "Loading chart..."}</Text>
      {rows.map((row, i) => (
        <View key={i} style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
          <Text style={{ width: 64 }}>{row.label}</Text>
          <View
            style={{
              height: 12,
              borderRadius: 6,
              backgroundColor: "#5057cc",
              width: `${((row.value ?? 0) / max) * 70}%`,
            }}
          />
        </View>
      ))}
    </View>
  );
}

Register it with useComponent, in any component under CopilotKitProvider:

src/ChatScreen.tsx
import { useComponent } from "@copilotkit/react-native/headless";
import { CopilotChat } from "@copilotkit/react-native/components";
import { BarChart, barChartPropsSchema } from "./BarChart";

export function ChatScreen() {
  useComponent({
    name: "render_bar_chart",
    description: "Show numeric data as a bar chart.",
    parameters: barChartPropsSchema,
    render: BarChart,
  });

  return <CopilotChat />;
}

BarChart is your own component. It reads only its props and knows nothing about CopilotKit. Any React Native charting library works here too.

parameters is optional, but leaving it out advertises the tool with an empty parameter schema. The model then has nothing to fill in, so it calls the tool with no arguments and your component renders with no props. Pass a schema for any component that needs data.

The name you pass to useComponent is what the agent sees as the tool name. Make it a verb, like render_bar_chart or show_weather, so the model picks it when the user asks for that view. CopilotKit adds a line to the description that tells the model the tool displays a component.

To check it, ask the agent for a bar chart of quarterly sales. The chart renders in the chat with the data from the agent.

React Native rules for the component

  • Props stream in. The component renders while the agent is still writing the arguments, so a field can be undefined or a list can be half full. Guard every prop, as BarChart does.
  • Wrap text in Text. The chat draws your component inside a FlatList. A bare string, outside a Text, throws Text strings must be rendered within a <Text> component.
  • Bound long content. For content whose length you can't predict, use a ScrollView with a maxHeight, so a long answer scrolls instead of pushing the chat off screen.

Where the component renders

The rendered CopilotChat and CopilotModal from /components draw registered components for you. The root CopilotChat, CopilotPopup, and CopilotSidebar do not draw messages, so no tool call shows there unless you render it. The component is registered and the agent calls it, but nothing appears.

In your own chat, call useRenderToolCall() and render each tool call in your list:

import { useRenderToolCall } from "@copilotkit/react-native/headless";

const renderToolCall = useRenderToolCall();

// For each tool call on an assistant message:
renderToolCall({ toolCall, toolMessage });

toolMessage is the tool-role message whose toolCallId matches the call. It returns a React Native element, or null when nothing is registered for that tool. See Headless UI for a full list.

For every option, see the useComponent reference.

How is this guide?