useCopilotChatHeadless

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

This is a premium-only feature

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