---
title: "useCopilotAction"
description: "A hook for providing actions the Copilot can call."
---

<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=a9b290bb-38f9-4518-ac3b-8f54fdbf43be" />

`useCopilotAction` is a React hook that lets you integrate
actionable functions in the Copilot chat. The Copilot can then call these
actions to trigger actions in your application, allowing for interactive
and dynamic behavior controlled by the Copilot.

You can define actions with parameters of any complexity. CopilotKit will relay
these definitions to the LLM and subsequently invoke your action handler with the
parameters you've defined.

In addition, the types of all parameters in your action handler are automatically
inferred from the action definition. This enables the use of TypeScript for
ensuring type safety and enabling autocompletion in your action handlers.

useCopilotAction takes an optional `render()` function that lets you render a
custom component or string instead of the default message component.

<RequestExample>
  ```jsx useCopilotAction Example
  useCopilotAction(
    {
      name: "sayHello",
      description: "Say hello to someone.",
      parameters: [
        {
          name: "name",
          type: "string",
          description: "name of the person to say greet",
        },
      ],
      handler: async ({name}) => {
        alert(`Hello, ${name}!`);
      },
    }
  );
````
</RequestExample>

## Parameters

<ResponseField name="action" type="Action" required>
  The function made available to the Copilot. See [Action](#action).
</ResponseField>

<ResponseField name="dependencies" type="any[]">
  An optional array of dependencies.
</ResponseField>

## Action

<ResponseField name="name" type="string" required>
  The name of the action.
</ResponseField>

<ResponseField name="description" type="string">
  A description of the action. This is used to instruct the Copilot on how to
  use the action.
</ResponseField>

<ResponseField name="parameters" type="Parameter[]">
  The parameters of the action. See [Parameter](#parameter).
</ResponseField>

<ResponseField name="handler" type="(args) => Promise<any>" required>
  The handler of the action.
</ResponseField>

<ResponseField name="render" type="function | string">
  Render lets you define a custom component or string to render instead of the
  default.

In the simplest case, you can provide a string to render a text message.

```js
{
  // ...
  render: "Hello, world!",
}
```

You can also provide a function to dynamically set the content of the message.

```js
{
  // ...
  render: ({status, args, result}) => status === "complete" ? "Done!" : "Processing...",
}
```

In this case, `status` is the execution status of the action, `args` are the
possibly incomplete, streaming arguments, and `result` is the result of the action.

Finally, you can return a React component to render a custom component.

```js
{
  // ...
  render: ({status, args, result}) => (
    <div>
      {status === "complete" ? "Done!" : "Processing..."}
    </div>
  ),
}
```

</ResponseField>

## Parameter

<ResponseField name="name" type="string" required>
  The name of the parameter.
</ResponseField>

<ResponseField
  name="type"
  type="'string' | 'number' | 'boolean' | 'object' | 'string[]' | 'number[]' | 'boolean[]' | 'object[]'"
  required
>
  The type of the argument.
</ResponseField>

<ResponseField name="description" type="string">
  A description of the argument. This is used to instruct the Copilot on what
  this argument is used for.
</ResponseField>

<ResponseField name="required" type="boolean">
  Wether or not the argument is required. Defaults to true.
</ResponseField>

<ResponseField name="attributes">
If the argument is of a complex type, i.e. `object` or `object[]`, this field
lets you define the attributes of the object. For example:
```js
{
  name: "addresses",
  description: "The addresses extracted from the text.",
  type: "object[]",
  attributes: [
    {
      name: "street",
      type: "string",
      description: "The street of the address.",
    },
    {
      name: "city",
      type: "string",
      description: "The city of the address.",
    },
    // ...
  ],
}
````
</ResponseField>