useRenderTool.mdx

title	useRenderTool
description	Register a React Native component to render inline when an agent calls a tool.

Overview

useRenderTool is the React Native counterpart of the web tool-rendering hooks. It registers a tool with the agent and a render function that produces a React Native element for that tool's call, so the agent can drive inline generative UI inside the chat. It combines useFrontendTool (registration + optional handler) with a render registry that the prebuilt CopilotChat reads when displaying tool calls.

The web-only rendering hooks (`useRenderToolCall`, `useDefaultRenderTool`, `useRenderActivityMessage`, `useRenderCustomMessages`) are **not** exported on React Native, because they depend on DOM elements. Use `useRenderTool` instead.

Signature

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

function useRenderTool<T>(
  options: UseRenderToolOptions<T>,
  deps?: ReadonlyArray<unknown>,
): void;

Parameters

Tool definition and render function. Unique tool name. Must match the name the agent calls. Human-readable description shown to the agent. Schema describing the tool's parameters. Accepts any schema compatible with [Standard Schema](https://standardschema.dev/) (Zod, Valibot, ArkType, etc.). Render function returning a React Native element for the tool call. Optional handler executed when the tool is called. Omit for a render-only tool. Optional agent ID to scope the tool to a specific agent. Optional dependency array. Re-register the tool when these values change.

RenderToolProps<T>

Props passed to your render function.

Parsed tool-call arguments, typed by your `parameters` schema. Current tool-call status. Result from the handler, when available.

Usage

import { useRenderTool } from "@copilotkit/react-native";
import { ActivityIndicator, Text, View } from "react-native";
import { z } from "zod";

function ChatScreen() {
  useRenderTool({
    name: "showWeather",
    description: "Display weather for a city",
    parameters: z.object({
      city: z.string(),
      temp: z.number(),
      condition: z.string(),
    }),
    render: ({ args, status }) => (
      <View style={{ padding: 12, backgroundColor: "#f0f0f0", borderRadius: 8 }}>
        <Text style={{ fontWeight: "bold" }}>{args.city}</Text>
        <Text>{args.temp}°C · {args.condition}</Text>
        {status === "executing" && <ActivityIndicator />}
      </View>
    ),
  });

  return <CopilotChat agentName="default" />;
}

Behavior

• Render returns ReactElement | null, not ReactNode. React Native's FlatList cannot render bare strings or portals, so a render function must return an element or null.
• Cleanup: unmounting unregisters both the tool and its render function.

RenderToolProvider and useRenderToolRegistry

These power the render registry and are installed automatically by CopilotKitProvider. You rarely use them directly.

Maintains the registry of tool render functions. Already mounted by `CopilotKitProvider`; add it manually only for an isolated subtree. Returns the `Map` of registered render functions, subscribing to changes via `useSyncExternalStore`. Used internally by `CopilotChat` to look up a renderer for each tool call. Throws if called outside a `RenderToolProvider`.

Related

• useFrontendTool: register a tool without inline rendering
• useHumanInTheLoop: gate a tool call on user approval