CopilotKit

useCopilotChatHeadless_c

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. Open the complete export map.

useCopilotChatHeadless_c is for building fully custom UI (headless UI) implementations.

This is a CopilotKit Intelligence feature

Sign up for free on Copilot Cloud to get your public license key or read more about CopilotKit Intelligence.

Usage is generous, free to get started, and works with either self-hosted or Copilot Cloud environments.

Key Features

  • Fully headless: Build your own fully custom UI's for your agentic applications.
  • Advanced Suggestions: Direct access to suggestions array with full control
  • Interrupt Handling: Support for advanced interrupt functionality
  • MCP Server Support: Model Context Protocol server configurations
  • Chat Controls: Complete set of chat management functions
  • Loading States: Comprehensive loading state management

Usage

Basic Setup

import { CopilotKit } from "@copilotkit/react-core";
import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
 
export function App() {
  return (
    <CopilotKit publicApiKey="your-free-public-license-key">
      <YourComponent />
    </CopilotKit>
  );
}
 
export function YourComponent() {
  const { messages, sendMessage, isLoading } = useCopilotChatHeadless_c();
 
  const handleSendMessage = async () => {
    await sendMessage({
      id: "123",
      role: "user",
      content: "Hello World",
    });
  };
 
  return (
    <div>
      {messages.map(msg => <div key={msg.id}>{msg.content}</div>)}
      <button onClick={handleSendMessage} disabled={isLoading}>
        Send Message
      </button>
    </div>
  );
}

Working with Suggestions

import { useCopilotChatHeadless_c, useCopilotChatSuggestions } from "@copilotkit/react-core";
 
export function SuggestionExample() {
  const {
    suggestions,
    setSuggestions,
    generateSuggestions,
    isLoadingSuggestions
  } = useCopilotChatHeadless_c();
 
  // Configure AI suggestion generation
  useCopilotChatSuggestions({
    instructions: "Suggest helpful actions based on the current context",
    maxSuggestions: 3
  });
 
  return (
    <div>
      {suggestions.map(suggestion => (
        <button key={suggestion.title}>{suggestion.title}</button>
      ))}
      <button onClick={generateSuggestions} disabled={isLoadingSuggestions}>
        Generate Suggestions
      </button>
    </div>
  );
}

Return Values

The following properties are returned from the hook:

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type