useRenderToolCall

Overview

useRenderToolCall returns a renderer function that maps tool calls to React elements. The returned function looks up the first matching render configuration by tool name (falling back to a wildcard "*" renderer if no exact match is found), parses the JSON arguments, determines the current ToolCallStatus, and returns the appropriate React element. When neither a per-tool nor a wildcard renderer is registered, it falls back to the framework's built-in DefaultToolCallRenderer, so the returned element is effectively always non-null (the signature keeps ReactElement | null for type compatibility).

This hook is primarily used by chat UI components to display visual feedback for tool calls. In most applications you will not call it directly; instead, you register render components via useFrontendTool or useHumanInTheLoop, and the chat components use useRenderToolCall internally to resolve them.

Signature

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

function useRenderToolCall(): (
  props: UseRenderToolCallProps,
) => React.ReactElement | null;

Return Value

Status Resolution

The renderer determines the ToolCallStatus based on the inputs:

ToolCallStatus

The ToolCallStatus enum is exported from @copilotkit/react-core/v2:

Usage

Using the Renderer in a Custom Chat Component

function CustomChatMessage({ message }) {
  const renderToolCall = useRenderToolCall();

  if (message.type === "tool_call") {
    // Always returns an element: your registered renderer, the wildcard
    // ("*") renderer, or the framework's built-in DefaultToolCallRenderer.
    const element = renderToolCall({
      toolCall: message.toolCall,
      toolMessage: message.toolMessage,
    });

    return <div className="tool-call-container">{element}</div>;
  }

  return <div>{message.content}</div>;
}

Registering Renderers with useFrontendTool

Tool call renderers are typically registered through useFrontendTool or directly via the renderToolCalls prop on the provider. The useRenderToolCall hook resolves these registrations at render time.

function App() {
  // Register a tool with a render component
  useFrontendTool(
    {
      name: "searchDatabase",
      description: "Search the product database",
      parameters: z.object({
        query: z.string().describe("Search query"),
      }),
      handler: async ({ query }) => {
        const results = await fetch(`/api/search?q=${query}`);
        return JSON.stringify(await results.json());
      },
      render: ({ args, status, result }) => {
        if (status === ToolCallStatus.InProgress) {
          return <div>Searching for "{args.query}"...</div>;
        }
        if (status === ToolCallStatus.Complete && result) {
          const data = JSON.parse(result);
          return (
            <div>
              <p>
                Found {data.length} results for "{args.query}"
              </p>
              <ul>
                {data.map((item: any) => (
                  <li key={item.id}>{item.name}</li>
                ))}
              </ul>
            </div>
          );
        }
        return null;
      },
    },
    [],
  );

  return <ChatInterface />;
}

Wildcard Renderer

If no exact name match is found, the hook falls back to a wildcard "*" renderer. This is useful for providing a generic UI for all unhandled tool calls.

function App() {
  return (
    <CopilotKit
      runtimeUrl="/api/copilotkit"
      renderToolCalls={[
        {
          name: "*",
          render: ({ name, args, status, result }) => {
            if (status === ToolCallStatus.InProgress) {
              return (
                <div className="text-gray-500 text-sm">Running {name}...</div>
              );
            }
            if (status === ToolCallStatus.Complete) {
              return (
                <div className="text-green-600 text-sm">{name} completed.</div>
              );
            }
            return null;
          },
        },
      ]}
    >
      <YourApp />
    </CopilotKit>
  );
}

Behavior

• Name-based lookup: The renderer searches registered render configurations for an exact tool name match first, then falls back to a wildcard ("*") renderer, and finally to the framework's built-in DefaultToolCallRenderer.
• JSON parsing: The tool call's args string is parsed from JSON before being passed to the render component. If parsing fails, args default to an empty object.
• Status inference: Status is determined from the presence and state of the toolMessage prop. The render component always receives a consistent shape with name, args, status, and result.
• Default renderer for unmatched tools: If no renderer is registered for the tool name and no wildcard renderer exists, the function falls back to the built-in DefaultToolCallRenderer rather than returning null, so unhandled tool calls still paint out-of-the-box.
• Used internally by chat components: The built-in CopilotChat, CopilotPopup, and CopilotSidebar components use this hook to render tool calls. You only need to call it directly when building custom chat UIs.

Related

• useFrontendTool -- register tools with render components
• useHumanInTheLoop -- register interactive tools with render components
• CopilotKit -- configure static render tool calls at the provider level