useCopilot()

The useCopilot() hook lets you access the internal state of the Copilot (eg, the messages), and control it headlessly (eg, call prompt). This is useful to build your own chat UI. The hook must be used inside a CopilotProvider.

Signature

const copilot = useCopilot()

The copilot instance has the following keys:

Key	Description	Type
isReady	Is the component initialized, and ready to accept method calls.	boolean
snapshot	The undo snapshot of the Copilot. Example.	Snapshot
threads	A list of all conversation threads associated with the user. Example.	Thread[]
selectedThreadId	The ID of the conversation thread that is currently selected.	string
selectThread(threadId)	Function that selects an existing conversation thread by ID. Example.	(string) => void
createThread()	Function that creates a new conversation thread. Example.	() => Promise<Thread>
createAndSelectThread()	Function that creates and selects a new conversation thread. Example.	() => Promise<Thread>
status	The status of the selected thread. Example.	Status
messages	The list of messages in the selected thread. Example.	Message[]
prompt(text)	Function that creates a new user message in the selected thread. Example.	(string) => void
cancel()	Function that cancels the prompt in progress, if any, in the selected thread. Example.	() => void
appId	Prop of CopilotProvider.	string
userId	Prop of CopilotProvider.	string
companyId	Prop of CopilotProvider.	string
context	Prop of CopilotProvider.	Context
inference	Prop of CopilotProvider.	Inference

snapshot

An object whose purpose is to enable undo in the chat UI.

{
  "isRunning": false,
  "lastOkRunId": "run_LsXG3FS1ph9qcYUKtPEfFO3s"
}

threads

A list of all conversation threads associated with the user.

[
  {
    "id": "thread_UI2a7ETtYwHiUTfQQ7gkZgyD",
    "object": "thread",
    "createdAt": 1727886647
  },
  {
    "id": "thread_u60hhejM8B8D50kFilkt6V9Q",
    "object": "thread",
    "createdAt": 1727948328
  }
]

selectThread(threadId)

Selects an existing conversation thread by ID.

copilot.selectThread('thread_UI2a7ETtYwHiUTfQQ7gkZgyD')

createThread()

Creates a new conversation thread.

const newThread = await copilot.createThread()

createAndSelectThread()

Create and selects a new conversation thread.

const newThread = await copilot.createAndSelectThread()

status

A string with the status of the selected thread. Possible values are:

• idle
• working
• cancelling

messages

A list of messages in the selected thread.

[
  {
    "id": "msg_oYXpd3JDvnQUMNevgRbrzfZc",
    "object": "thread.message",
    "threadId": "thread_u60hhejM8B8D50kFilkt6V9Q",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": {
          "value": "Add 2 circles.",
          "annotations": []
        }
      }
    ],
    "isUndoable": null,
    "isRedoable": null
  },
  {
    "id": "calls_XKBb4ouI2RYyix0FXS7vDCUY",
    "object": "thread.tool_calls",
    "threadId": "thread_u60hhejM8B8D50kFilkt6V9Q",
    "status": "completed",
    "toolCalls": [
      {
        "id": "call_E7ydiajRTd5GulDCxtSARQ8z",
        "type": "function",
        "function": {
          "name": "runProgram",
          "arguments": "{\"program\":\"createShape({ type: 'ellipse', cx: 50, cy: 50, rx: 25, ry: 25, color: 'red' });\\ncreateShape({ type: 'ellipse', cx: 150, cy: 150, rx: 25, ry: 25, color: 'blue' });\\n__copilotSetOutput('Done, I added 2 circles.')\"}",
          "output": "Done, I added 2 circles."
        }
      }
    ],
    "isUndoable": false,
    "isRedoable": false
  },
  {
    "id": "msg_LRygNISEWDKEYmLYCKolmq76",
    "object": "thread.message",
    "threadId": "thread_u60hhejM8B8D50kFilkt6V9Q",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": {
          "value": "I've added 2 circles for you.",
          "annotations": []
        }
      }
    ],
    "isUndoable": false,
    "isRedoable": false
  }
]

prompt(text)

Creates a new user message in the selected thread.

Argument	Description	Type	Required
text	The user message.	string	yes

copilot.prompt('Add 2 concentric circles.')

cancel()

Cancels the prompt in progress, if any, in the selected thread.

copilot.cancel()

Example

// Example.jsx
import { CopilotProvider, useCopilot } from '@copilotjs/react'

export default function Example() {
  return (
    <CopilotProvider appId="..." userId="..." companyId="..." context={...}>
      <MyChat />
    </CopilotProvider>
  )
}

function MyChat() {
  // Access the copilot instance, and build your chat UI.
  const copilot = useCopilot()
  return (
    <>
      <div>Threads: {JSON.stringify(copilot.threads)}</div>
      <div>Selected thread: {copilot.selectedThreadId}</div>
      <div>Status: {copilot.status}</div>
      <div>Messages: {JSON.stringify(copilot.messages)}</div>
      <button onClick={async () => await copilot.createAndSelectThread()}>New thread</button>
      <button onClick={() => copilot.prompt('Add 2 circles.')}>Prompt</button>
      <button onClick={() => copilot.cancel()}>Cancel</button>
    </>
  )
}