useRenderTool
Register a React Native renderer for a tool call, by tool name or wildcard.
Overview
useRenderTool registers a renderer only. It supplies UI for a tool call
somebody else owns: a server-side tool, or, with name: "*", every tool call
that has no renderer of its own. It does not register a tool: nothing is
advertised to the model and nothing becomes callable.
That contract is react-core's, so this page and the React (V2)
useRenderTool describe the same behaviour;
only the import path differs.
Registering a tool is a different hook
If you want the agent to be able to call your function and draw its UI, that
is useFrontendTool. It
accepts description, handler and render, and it advertises the tool to
the model on every run. A renderer-only registration does neither: nothing
offered to the model, nothing callable. To register a tool whose renderer is a
component, use useComponent. To
wait for the user's approval, use
useHumanInTheLoop.
Upgrading from an older React Native release
If your code passes description or handler to this hook, see Migrating
from the old React Native
useRenderTool for what
to change and what the compiler does not catch.
Signature
There are two overloads: a wildcard fallback that takes no schema, and a name-scoped renderer that requires one.
Wildcard overload
import { useRenderTool } from "@copilotkit/react-native";
useRenderTool(
{
name: "*",
render: (props: any) => React.ReactElement | null,
agentId?: string,
group?: boolean,
},
deps?: ReadonlyArray<unknown>,
);Named overload
import { useRenderTool } from "@copilotkit/react-native";
import { z } from "zod";
useRenderTool<S extends StandardSchemaV1>(
{
name: string,
parameters: S,
render: (props: RenderToolProps<S>) => React.ReactElement | null,
agentId?: string,
group?: boolean,
},
deps?: ReadonlyArray<unknown>,
);S is the schema type, not the parsed argument object. The shape of
props.parameters inside render is inferred from it.
Parameters
Prop
Type
RenderToolProps<S>
Props passed to your render function on the named overload.
@copilotkit/react-native re-exports this type from react-core, so React Native
and web cannot drift apart:
import type { RenderToolProps } from "@copilotkit/react-native";It is a three-arm union discriminated on status. parameters is
Partial<InferSchemaOutput<S>> on the in-progress arm and the full
InferSchemaOutput<S> on the executing and complete arms; result is a
string only on the complete arm. Narrow on status before reading
parameters fields or result.
S has no default, so the type argument is required: a bare
RenderToolProps is TS2314: Generic type 'RenderToolProps' requires 1 type argument(s). Pass the schema's type (RenderToolProps<typeof mySchema>) or,
for a renderer with no schema of its own, RenderToolProps<z.ZodTypeAny>.
Prop
Type
RenderToolInProgressProps, RenderToolExecutingProps, RenderToolCompleteProps
@copilotkit/react-native re-exports these three types from react-core. They are
the arms of the RenderToolProps<S> union above, so you can name a single
state directly:
import type { RenderToolCompleteProps } from "@copilotkit/react-native";
import { Text } from "react-native";
import { z } from "zod";
const schema = z.object({ city: z.string() });
function WeatherResult(props: RenderToolCompleteProps<typeof schema>) {
// `props.parameters.city` is a `string`, and `props.result` is a `string`.
return <Text>{props.parameters.city}: {props.result}</Text>;
}Each is generic over the schema (S extends StandardSchemaV1), matching
RenderToolProps<S>.
Usage
import { useRenderTool } from "@copilotkit/react-native";
import { CopilotChat } from "@copilotkit/react-native/components";
import { ActivityIndicator, Text, View } from "react-native";
import { z } from "zod";
function ChatScreen() {
useRenderTool(
{
// A tool your agent executes server-side; this only draws it.
name: "showWeather",
parameters: z.object({
city: z.string(),
temp: z.number(),
condition: z.string(),
}),
render: ({ status, parameters }) => {
if (status === "inProgress") return <ActivityIndicator />;
return (
<View
style={{ padding: 12, backgroundColor: "#f0f0f0", borderRadius: 8 }}
>
<Text style={{ fontWeight: "bold" }}>{parameters.city}</Text>
<Text>
{parameters.temp}°C · {parameters.condition}
</Text>
</View>
);
},
},
[],
);
return <CopilotChat agentName="default" />;
}Import CopilotChat from the /components subpath. That is the prebuilt UI
that reads the render registry and paints tool calls inline; the CopilotChat
exported from the @copilotkit/react-native root is
headless and renders no message
list, so a registered render would never appear.
Wildcard fallback
A "*" entry draws any tool call that has no exact-name renderer. It takes no
schema, so its render props are untyped:
useRenderTool(
{
name: "*",
render: ({ name, status }) => (
<Text>
{status === "complete" ? "✓" : "⏳"} {name}
</Text>
),
},
[],
);Returning null from a renderer draws nothing, so render: () => null is how
you silence a tool call: one named tool, or, with "*", every tool that has no
renderer of its own.
Behavior
- Renderer only. Nothing is added to the tool list the runtime hands the agent, and the model cannot call a name registered here.
renderreturnsReactElement | null, notReactNode. React Native'sFlatListcannot render bare strings or portals, and this signature enforces it.- Deduplicated by
agentId:name. The latest registration under a key wins. - Arguments stream. While the agent is still writing the call,
statusis"inProgress"andparametersis partial. Fields arrive progressively. Write renderers that tolerate missing fields; that is what lets UI build as the agent writes it. renderis captured at registration. It is not refreshed on every render, only when the renderer re-registers, which happens whennamechanges or whendepscompare as changed. If yourrendercloses over component state or props that change over time, list them indeps, or read them through a ref (see below); otherwise the chat keeps invoking the stale closure and paints outdated UI.- No cleanup on unmount. The renderer entry is deliberately kept, so tool calls already in the chat history still render after you navigate away.
Dependency comparison
The hook reduces deps to a version number
(source)
and never serializes it:
- Plain data compares by value: strings, numbers, booleans,
null,undefined, dates, and plain objects and arrays of those. An inline literal such as[{ status }]or[items.filter(isOpen)]re-registers only when its contents change. Key order does not matter. - A function never counts as changed: a new callback in
depsdoes not re-register the renderer. Read a changing callback through a ref (below). - Class instances,
Map,Setand other non-plain objects compare by identity. - A circular value, such as the
agentreturned byuseAgent, is safe to list. A cycle inside plain data is safe too. - Adding or removing an entry counts as a change.
When what changes is behavior rather than displayed data, a ref avoids
re-registering at all. Keep the value in a ref that render dereferences when
it runs:
function SeatPicker({ onSelect }: { onSelect: (id: string) => void }) {
// Reassigned on every render; the captured `render` reads it at call time.
const onSelectRef = useRef(onSelect);
onSelectRef.current = onSelect;
useRenderTool(
{
name: "pickSeat",
parameters: z.object({ seats: z.array(z.string()) }),
render: ({ parameters }) => (
<SeatGrid
seats={parameters.seats ?? []}
onSelect={(id) => onSelectRef.current(id)}
/>
),
},
[],
);
}The captured render is still the stale one, but the ref it reads is current, so
the renderer never has to re-register to reach the newest callback. That makes the
ref pattern the more reliable default whenever what changes is behavior rather
than displayed data.
Rendering a tool call outside the chat
CopilotChat renders tool calls inline. To render a registered component anywhere else (a dashboard, a kiosk, a full-screen stage the agent composes), call useRenderToolCall() inside a component mounted under CopilotKitProvider, and read the tool calls off the agent's own message list:
import { useAgent, useRenderToolCall } from "@copilotkit/react-native";
import { View } from "react-native";
function ToolCallStage({ agentId = "default" }: { agentId?: string }) {
const { agent } = useAgent({ agentId });
const renderToolCall = useRenderToolCall();
const messages = agent.messages ?? [];
// Pair each call with its result message — the same correlation the prebuilt
// chat does. `toolMessage` is what selects the complete arm: pass it and the
// call resolves to `"complete"` with `result`. Without one, `result` is
// `undefined` and the status comes from the provider instead — `"executing"`
// while this call id is one the provider is tracking as executing, and
// `"inProgress"` otherwise.
const toolMessages = new Map(
messages.flatMap((message) =>
message.role === "tool" ? [[message.toolCallId, message] as const] : [],
),
);
const toolCalls = messages.flatMap((message) =>
message.role === "assistant" ? (message.toolCalls ?? []) : [],
);
// Each returned element is already keyed by tool-call id.
return (
<View>
{toolCalls.map((toolCall) =>
renderToolCall({
toolCall,
toolMessage: toolMessages.get(toolCall.id),
}),
)}
</View>
);
}Prop
Type
Import useRenderToolCall from @copilotkit/react-native.
useDefaultRenderTool, useRenderActivityMessage, and
useRenderCustomMessages are web only.
Migrating from the old React Native useRenderTool
Read this section only if your React Native code called useRenderTool on a
release before 1.72. New code does not need it.
React Native used to export a local hook under this name. It was not
react-core's useRenderTool: its whole body forwarded to react-core's other
hook, useFrontendTool, so it registered a tool and a renderer while
carrying the renderer-only hook's name.
1.71 deleted that hook and pointed the name at react-core's, behind a deprecated
compatibility shim that routed an old-shaped call the way the old hook did and
warned about it in development. The shim is gone. @copilotkit/react-native
now re-exports react-core's useRenderTool itself and carries no render-tool
implementation of its own, so this page describes the whole of what the name
does.
What to change
Most rows below are compile errors, so the compiler will bring you here for those whether or not you read this page first. The exception is the first row, which fails only where TypeScript's excess-property check reaches it. See three shapes the compiler cannot see for the call shapes it does not.
Because the hook is overloaded, an excess description or handler is
reported as TS2769: No overload matches this call rather than the bare
TS2353 you would get on a single-signature function. The excess property is
named in the nested per-overload detail, so read past the first line.
| Before (old RN hook) | Change it to | What happens if you don't |
|---|---|---|
useRenderTool({ name, description, parameters, handler, render }, deps) | useFrontendTool({ …identical object }, deps) (rename only) | TS2769: No overload matches this call, naming description under the named overload. But see three shapes the compiler cannot see, where it compiles and the tool silently stops being registered |
renderer-only registration: impossible in TypeScript (description was required), reachable from plain JS | useRenderTool({ name, parameters, render, agentId? }, deps) (parameters required on a named renderer) | already correct; nothing to do |
wildcard: registers a tool named * | useRenderTool({ name: "*", render }) (the one case that takes no schema) | TS2769: description / handler / parameters are not on this overload; drop them |
render props { args, status, … } | { parameters, status, … } | TS2339: Property 'args' does not exist on type 'RenderToolProps<…>'. (The wildcard overload types its props as any, so args still compiles there.) |
RenderToolProps<T> (args-shaped, generic over parsed args) | RenderToolProps<S> (parameters-shaped, generic over schema) | re-exported from react-core |
bare RenderToolProps (RN's had T = Record<string, unknown>) | RenderToolProps<typeof mySchema> | TS2314: Generic type 'RenderToolProps' requires 1 type argument(s). core's S has no default, so the natural spelling for an untyped renderer no longer compiles |
UseRenderToolOptions<T> | gone. Write the config inline (RenderToolConfig is core-internal) | TS2305 on the import |
RenderToolFunction<T> | for a useRenderTool renderer, nothing: the hook already declares render as ReactElement | null. For a useFrontendTool renderer, FrontendToolRenderFunction<T> | TS2305 on the import |
Write the config as an inline object literal, and let the overload infer its
type. To type a standalone render function, use RenderToolProps<S>.
If your call site wanted a callable tool, useFrontendTool is a rename and
nothing else. It takes the same object, description and handler included.
If it only ever drew UI for a tool the agent already had, drop description
(and handler, if you passed one) and rename args to parameters.
On the old hook, name: "*" registered a frontend tool named * with no
handler. Core runs the * tool for a tool call that has no frontend tool and no
result yet, so that tool answered those calls with an empty result and asked for
another turn. On core's hook, "*" is what it is on the web: a schema-less
fallback renderer that registers no tool at all.
Three shapes the compiler cannot see
description and handler are compile errors on this hook now. But they fail only where
TypeScript's excess-property check actually fires, which is on properties
written inline in a fresh object literal. Three shapes slip past it, and all
three compile clean while the tool silently stops being registered: nothing is
advertised to the model any more, and handler never runs again.
They are also the shapes that look unchanged on screen. React-core's renderer
bridge spreads { ...props, parameters: props.args } into your renderer, so an
old render: ({ args }) => … keeps painting exactly as it did. The UI is
identical; the tool is gone. The deprecated shim that shipped in 1.71 warned
about precisely this population in development. With the shim gone, nothing
does. Audit these by hand.
-
A hoisted config object. Assign the config to a variable first and pass the variable, and the excess
descriptionis no longer excess:const cfg = { name: "showWeather", description: "Show weather info", parameters: z.object({ city: z.string() }), handler: async ({ city }: { city: string }) => fetchWeather(city), render: () => <WeatherCard city="Berlin" />, // ignores its props }; useRenderTool(cfg); // compiles clean, registers a renderer and nothing elseA hoisted config whose
renderdoes destructureargsis caught either way. The render parameter is contravariant, so it fails onrender. The problem is specifically the "hoisted andrenderignores its props" combination. -
Spread-carried fields. Same cause, and it survives a fresh literal at the call site: excess-property checking does not reach a property that arrives via a spread, so the old
descriptionis not flagged.const base = { name: "showWeather", description: "Show weather", parameters: z.object({ city: z.string() }), }; useRenderTool({ ...base, render: () => <WeatherCard city="Berlin" /> }); // compiles cleanExactly as above, a
renderthat does destructureargsis caught on contravariance. -
An untyped call site. A plain-JavaScript screen, or one under
@ts-nocheck, is checked by nothing at all.
If you have JavaScript React Native screens, grep them for useRenderTool and
decide per call site whether it wanted a tool (useFrontendTool) or only a
renderer. The compiler will never do it for you on those files.
The shape that looks correct either way
{ name, parameters, render } (no description, no handler) is the one call
that is simultaneously:
- the correct renderer-only spelling, which is what this page documents; and
- an old plain-JS call that used to register and advertise a real tool.
Both are the same object, and nothing distinguishes them. description was
required by the old hook's types, so a TypeScript caller could never write this
shape. But an untyped JavaScript caller could. On the old hook, handler was
optional and nothing filtered a tool out for lacking one, so
{ name, parameters, render } registered and advertised name to the model
with an empty description.
Today it registers a renderer and nothing else. If you were relying on it
advertising a tool, move the call to
useFrontendTool. If you only
ever wanted to draw UI for a tool somebody else owns, it is already correct.
status is not a break
The old hook's render props typed status as the ToolCallStatus enum;
core's RenderToolProps types it as the string literals "inProgress" | "executing" | "complete". No migration work follows from that. A
string-enum member is assignable to its own literal type, so
status === ToolCallStatus.Complete compiles and narrows against the literal
union. Existing enum comparisons keep working untouched. Either form is fine;
pick one and be consistent.
ToolCallStatus remains a value export of @copilotkit/react-native, and it is
still the shape you meet where the canonical ReactToolCallRenderer contract is
in play: a renderer built with defineToolCallRenderer, or a render passed to
useFrontendTool, receives status as an enum member.
How is this guide?