# useRenderTool

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

## Overview [#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`](/reference/hooks/useComponent), [`useDefaultRenderTool`](/reference/hooks/useDefaultRenderTool), and [`useRenderToolCall`](/reference/hooks/useRenderToolCall).

This hook only handles rendering. It does not register a frontend handler. To also run a handler in the browser, use [`useFrontendTool`](/reference/hooks/useFrontendTool).

## Signature [#signature]

### Wildcard overload [#wildcard-overload]

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

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

### Named overload [#named-overload]

```tsx
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-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 [#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`](/reference/components/CopilotChatMessageView#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 [#usage]

### Named tool renderer [#named-tool-renderer]

```tsx
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 [#wildcard-fallback-renderer]

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

  return null;
}
```

### Disable rendering for a tool [#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()`).

```tsx
import { z } from "zod";

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

  return null;
}
```
