useRenderToolCall

React hook that returns a renderer function for tool calls in the chat interface

Overview

Same name, different API than v1

The v2 useRenderToolCall (this page, from @copilotkit/react-core/v2) is a no-argument hook that returns a renderer function for consuming tool calls. It is not the v1 useRenderToolCall, which takes a { name, parameters, render } config object to register a renderer. To register renderers for existing backend tools in v2, use useRenderTool.

useRenderToolCall returns a renderer function that maps tool calls to React elements. The returned function:

  1. Finds the renderer for the tool name: one scoped to the active agentId, then an unscoped one, then a wildcard "*" renderer.
  2. Parses the partial JSON arguments.
  3. Sets the ToolCallStatus.
  4. Returns the React element.

When no named or wildcard renderer matches, the function returns null. In development it logs a warning that names the tool. To show a card for every tool call, call useDefaultRenderTool().

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 for existing backend tools via useRenderTool, 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

Prop

Type

Status Resolution

The renderer determines the ToolCallStatus based on the inputs:

ConditionStatusresult
No toolMessage, tool call id not in the executing setToolCallStatus.InProgressundefined
No toolMessage, tool call id is in the provider executing setToolCallStatus.Executingundefined
A toolMessage is presentToolCallStatus.CompleteThe result string from the tool message

ToolCallStatus

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

ValueDescription
ToolCallStatus.InProgressThe tool call's arguments are still being streamed.
ToolCallStatus.ExecutingArguments are fully resolved; the tool is executing.
ToolCallStatus.CompleteExecution is finished and a result is available.

Usage

Using the Renderer in a Custom Chat Component

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

  if (message.type === "tool_call") {
    // Returns your named renderer, the wildcard ("*") renderer, or null
    // when neither matches.
    const element = renderToolCall({
      toolCall: message.toolCall,
      toolMessage: message.toolMessage,
    });
    if (!element) return null;

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

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

Registering renderers

To register the renderers this function uses, see useRenderTool, or pass them in the renderToolCalls prop of CopilotKitProvider.

Behavior

  • Name-based lookup with agent scoping: The renderer searches registered render configurations for an exact tool name match first. When multiple match the same name, it prefers the one scoped to the active agentId, then an unscoped renderer, then the first match. If no exact match exists, it falls back to a wildcard ("*") renderer. If neither matches, it returns null.
  • Partial JSON parsing: The tool call's arguments string is parsed with partialJSONParse before being passed to the render component, so partially-streamed arguments can render incrementally while the tool call is still InProgress.
  • Status inference: Status is determined from the presence of the toolMessage prop and whether the tool call id is in the provider's executing set. The render component always receives a consistent shape with name, toolCallId, args, status, and result.
  • No renderer for unmatched tools: If no renderer is registered for the tool name and no wildcard renderer exists, the function returns null. In development it logs a warning that names the tool. Call useDefaultRenderTool() to show a built-in card for these tool calls.
  • 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.

How is this guide?