# useCopilotReadable

> The useCopilotReadable hook gives your copilot knowledge (e.g. application state).

## 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).

{
 /*
  * ATTENTION! DO NOT MODIFY THIS FILE!
  * This page is auto-generated. If you want to make any changes to this page, changes must be made at:
  * packages/react-core/src/v1-deprecated/hooks/use-copilot-readable.ts
  */
}
<Callout type="info">
  In v2, use [`useAgentContext`](/reference/v2/hooks/useAgentContext) from `@copilotkit/react-core/v2`.
</Callout>

`useCopilotReadable` is a React hook that provides app-state and other information
to the Copilot.

## Usage [#usage]

### Simple Usage [#simple-usage]

Pass a `description` and a `value`. The hook adds them to the context that the
Copilot reads when it answers.

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

export function MyComponent() {
  const [employees, setEmployees] = useState([]);

  useCopilotReadable({
    description: "The list of employees",
    value: employees,
  });
}
```

### Custom Serialization [#custom-serialization]

By default the value is serialized with `JSON.stringify`. Pass `convert` to
control the string the Copilot sees. It is called with the description and the
value, in that order:

```tsx
useCopilotReadable({
  description: "The current user",
  value: user,
  convert: (description, value) => `${description}: ${value.firstName} ${value.lastName}`,
});
```

### Conditional Usage [#conditional-usage]

Toggle `available` to add or remove the context as your app state changes.
Switching to `"disabled"` removes the entry from the Copilot context; switching
back to `"enabled"` re-adds it.

```tsx
useCopilotReadable({
  description: "The list of employees",
  value: employees,
  available: showEmployees ? "enabled" : "disabled",
});
```

### Re-running on Custom Dependencies [#re-running-on-custom-dependencies]

The context is refreshed whenever `description`, `value`, `convert` or
`available` change. Pass a second argument to add your own dependencies:

```tsx
useCopilotReadable(
  {
    description: "The selected employee",
    value: employee,
  },
  [departmentId],
);
```

## Return Value [#return-value]

`string | undefined`: the id of the context entry. It is `undefined` on the first
render and while `available` is `"disabled"`.

## Parameters [#parameters]

<PropertyReference name="description" type="string" required > 
The description of the information to be added to the Copilot context.
</PropertyReference>

<PropertyReference name="value" type="any" required > 
The value to be added to the Copilot context. Object values are automatically stringified.
</PropertyReference>

<PropertyReference name="available" type="'enabled' | 'disabled'"  > 
Whether the context is available to the Copilot.
</PropertyReference>

<PropertyReference name="convert" type="(description: string, value: any) => string"  > 
A custom conversion function to use to serialize the value to a string. If not provided, the value
will be serialized using `JSON.stringify`.
</PropertyReference>
