# useRenderToolCall

> The useRenderToolCall hook enables rendering of backend tool calls in the frontend.

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

<Callout type="warning">
  This v1 `useRenderToolCall` takes a `{ name, parameters, render }` config object to **register** a renderer for an existing backend tool. In v2, use [`useRenderTool`](https://docs.copilotkit.ai/reference/v2/hooks/useRenderTool) for that job. The v2 hook named [`useRenderToolCall`](/reference/v2/hooks/useRenderToolCall) is a different, low-level API that returns a renderer function for consuming tool calls.

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

function StatusTool() {
  useRenderTool({
    name: "showStatus",
    parameters: z.object({}),
    render: ({ status, result }) => (
      <div>{status === "complete" ? result : "Running..."}</div>
    ),
  });
  return null;
}
```

</Callout>

`useRenderToolCall` is purely a rendering hook. It displays custom UI for tool calls without executing
any logic. This is typically used to visualize backend tool executions in your chat interface, showing
users what the AI is doing behind the scenes.

This hook has no handler function. You only provide a render function that receives information about
the tool call (arguments, status, results) and displays it however you want. You can target specific
tool names or use an asterisk (`"*"`) to catch and render all tool calls.

## Usage [#usage]

### Rendering a Specific Backend Tool [#rendering-a-specific-backend-tool]

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

useRenderToolCall({
  name: "analyzeData",
  description: "Display results of data analysis",
  parameters: [
    {
      name: "datasetName",
      type: "string",
      description: "Name of the dataset being analyzed",
      required: true,
    },
    {
      name: "metrics",
      type: "string[]",
      description: "Metrics being calculated",
      required: true,
    },
  ],
  render: ({ args, status, result }) => {
    if (status === "inProgress") {
      return (
        <div className="p-4 border rounded animate-pulse">
          <h3>Analyzing {args.datasetName}...</h3>
          <p>Calculating: {args.metrics?.join(", ")}</p>
        </div>
      );
    }

    if (status === "complete" && result) {
      return (
        <div className="p-4 border rounded bg-green-50">
          <h3>Analysis Complete: {args.datasetName}</h3>
          <pre className="mt-2 p-2 bg-gray-100 rounded">
            {JSON.stringify(result, null, 2)}
          </pre>
        </div>
      );
    }

    return null;
  },
});
```

## Migration from useCopilotAction [#migration-from-usecopilotaction]

If you're migrating from `useCopilotAction` with only a `render` function:

```tsx
// Before with useCopilotAction
useCopilotAction({
  name: "showResult",
  render: ({ args }) => <ResultCard {...args} />,
});

// After with useRenderToolCall
useRenderToolCall({
  name: "showResult",
  render: ({ args }) => <ResultCard {...args} />,
});
```

The migration is straightforward - just change the hook name. The render props remain the same.

## Parameters [#parameters]

<PropertyReference name="name" type="string" required>
  The name of the tool to render. Use `"*"` to catch all tool calls.
</PropertyReference>

<PropertyReference name="description" type="string">
  A description of what this renderer does. Mainly for documentation purposes.
</PropertyReference>

<PropertyReference name="parameters" type="T"  >
Optional array of parameter definitions. If provided, adds type safety to the args in the render function. Each parameter object should have:
- `name` (string): The parameter name
- `type` (string): The parameter type (e.g., "string", "number", "boolean", "string[]", "object")
- `description` (string): A description of what the parameter is for
- `required` (boolean): Whether the parameter is required
- `attributes` (array, optional): For object types, define nested properties using the same schema

Simple example: `[{ name: "datasetName", type: "string", description: "Name of the dataset", required: true }]`

Nested example:

```typescript
[
  {
    name: "analysisConfig",
    type: "object",
    description: "Configuration for the analysis",
    required: true,
    attributes: [
      {
        name: "method",
        type: "string",
        description: "Analysis method to use",
        required: true,
      },
      {
        name: "threshold",
        type: "number",
        description: "Threshold value",
        required: false,
      },
    ],
  },
];
```

</PropertyReference>

<PropertyReference name="render" type="(props: ActionRenderProps<T>) => React.ReactElement" required>
  A function that returns the tool call UI. It receives props
  with `status`, `args`, `result`, and `name`.
</PropertyReference>

<PropertyReference name="available" type="'disabled' | 'enabled'">
  Currently non-functional in this v1 hook. The value is accepted for API
  compatibility but ignored, so setting `"disabled"` does not prevent the
  renderer from being registered.
</PropertyReference>

<PropertyReference name="dependencies" type="any[]">
  The second argument of the hook. When a value in it changes, the hook
  registers the renderer again.
</PropertyReference>
