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:

messagesMessage[]

The messages currently in the chat in AG-UI format

sendMessage(message: Message, options?) => Promise<void>

Send a new message to the chat and trigger AI response

setMessages(messages: Message[] | DeprecatedGqlMessage[]) => void

Replace all messages in the chat with new array

deleteMessage(messageId: string) => void

Remove a specific message by ID from the chat

reloadMessages(messageId: string) => Promise<void>

Regenerate the response for a specific message by ID

stopGeneration() => void

Stop the current message generation process

reset() => void

Clear all messages and reset chat state completely

isLoadingboolean

Whether the chat is currently generating a response

runChatCompletion() => Promise<Message[]>

Manually trigger chat completion for advanced usage

mcpServersMCPServerConfig[]

Array of Model Context Protocol server configurations

setMcpServers(servers: MCPServerConfig[]) => void

Update MCP server configurations for enhanced context

suggestionsSuggestionItem[]

Current suggestions array for reading or manual control

setSuggestions(suggestions: SuggestionItem[]) => void

Manually set suggestions for custom workflows

generateSuggestions() => Promise<void>

Trigger AI-powered suggestion generation using configured settings

resetSuggestions() => void

Clear all current suggestions and reset generation state

isLoadingSuggestionsboolean

Whether suggestions are currently being generated

interruptstring | React.ReactElement | null

Interrupt content for human-in-the-loop workflows

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:

messagesMessage[]

The messages currently in the chat in AG-UI format

sendMessage(message: Message, options?) => Promise<void>

Send a new message to the chat and trigger AI response

setMessages(messages: Message[] | DeprecatedGqlMessage[]) => void

Replace all messages in the chat with new array

deleteMessage(messageId: string) => void

Remove a specific message by ID from the chat

reloadMessages(messageId: string) => Promise<void>

Regenerate the response for a specific message by ID

stopGeneration() => void

Stop the current message generation process

reset() => void

Clear all messages and reset chat state completely

isLoadingboolean

Whether the chat is currently generating a response

runChatCompletion() => Promise<Message[]>

Manually trigger chat completion for advanced usage

mcpServersMCPServerConfig[]

Array of Model Context Protocol server configurations

setMcpServers(servers: MCPServerConfig[]) => void

Update MCP server configurations for enhanced context

suggestionsSuggestionItem[]

Current suggestions array for reading or manual control

setSuggestions(suggestions: SuggestionItem[]) => void

Manually set suggestions for custom workflows

generateSuggestions() => Promise<void>

Trigger AI-powered suggestion generation using configured settings

resetSuggestions() => void

Clear all current suggestions and reset generation state

isLoadingSuggestionsboolean

Whether suggestions are currently being generated

interruptstring | React.ReactElement | null

Interrupt content for human-in-the-loop workflows

useCopilotChatHeadless_c

Key Features

Usage

Basic Setup

Working with Suggestions

Return Values

On this page

useCopilotChatHeadless_c

Key Features

Usage

Basic Setup

Working with Suggestions

Return Values

On this page