useRenderTool

Register typed renderers for tool calls, by tool name or wildcard

Overview

useRenderTool registers a chat renderer for tool calls. You can target a specific tool name (with a typed parameters schema, for example Zod) or use a wildcard ("*") fallback renderer.

This is part of the v2 tool rendering hook set with useComponent, useDefaultRenderTool, and useRenderToolCall.

This hook only handles rendering. It does not register a frontend handler. To also run a handler in the browser, use useFrontendTool.

Signature

Wildcard overload

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

useRenderTool(
  {
    name: "*",
    render: (props) => React.ReactElement | null,
    agentId?: string,
    group?: boolean,
  },
  deps?: ReadonlyArray<unknown>,
);

Named overload

import { z } from "zod";
import { useRenderTool } from "@copilotkit/react-core/v2";

useRenderTool(
  {
    name: string,
    parameters: StandardSchemaV1,
    render: (props) => React.ReactElement | null,
    agentId?: string,
    group?: boolean,
  },
  deps?: ReadonlyArray<unknown>,
);

Render Props

render receives one of these states:

  • { status: "inProgress", parameters: Partial<T>, result: undefined }
  • { status: "executing", parameters: T, result: undefined }
  • { status: "complete", parameters: T, result: string }

name is always present in all states.

Behavior

  • render can return null to draw nothing for a tool call.
  • Builds a renderer entry with defineToolCallRenderer.
  • group: true lets the chat collapse calls this renderer draws into its tool-call groups (see toolCallDisplay). Leave it unset for renderers that are part of your UI, or that may draw nothing; their calls always show on their own.
  • Deduplicates by agentId:name key (latest registration wins).
  • Intentionally does not remove the renderer on cleanup so previous chat history can still render.
  • Tracks updates by config.name plus values in deps (include changing captures in deps).
  • deps comparison: compares plain data (strings, numbers, booleans, null, dates, and plain objects and arrays of those) by value, so an inline literal such as [{ status }] re-registers only when its contents change. A function never counts as changed, so keep a changing callback in a ref. Class instances and other objects compare by identity, so a circular value such as the agent from useAgent is safe to pass. Adding or removing an entry counts as a change.

Usage

Named tool renderer

function App() {
  useRenderTool(
    {
      name: "searchDocs",
      parameters: z.object({ query: z.string() }),
      render: ({ name, parameters, status, result }) => {
        if (status === "inProgress") return <div>Preparing {name}…</div>;
        if (status === "executing")
          return <div>Searching for: {parameters.query}</div>;
        return <div>Done: {result}</div>;
      },
    },
    [],
  );

  return null;
}

Wildcard fallback renderer

function App() {
  useRenderTool(
    {
      name: "*",
      render: ({ name, status }) => (
        <div>
          {status === "complete" ? "✓" : "⏳"} {name}
        </div>
      ),
    },
    [],
  );

  return null;
}

Disable rendering for a tool

If you call useDefaultRenderTool(), register a named renderer that returns null to hide one tool. A named tool takes a pass-through schema (z.any()).

import { z } from "zod";

function App() {
  // Hide one tool from the useDefaultRenderTool() card.
  useRenderTool(
    { name: "searchDocs", parameters: z.any(), render: () => null },
    [],
  );

  return null;
}

How is this guide?