Headless UI
Build the chat UI yourself with the `useCopilotChatHeadless_c` hook.
Overview
To build the chat UI yourself, use the useCopilotChatHeadless_c hook. You build the chat UI. CopilotKit still runs threads, generative UI, suggestions, and interrupts.
This hook needs a public license key.
Self-hosted and open-source projects use that key. A cloud-hosted project uses
CPK_INTELLIGENCE_API_KEY and does not include this hook. If the CopilotKit CLI
created your project, build the UI with the v2 primitives in
Headless UI.
Navigation
Getting started
Build a Headless UI chat from the ground up to get started.
Generative UI
Learn how to work with generative UI to render tools and other UI elements.
Suggestions
Learn how to work with suggestions to provide your users with a list of generated or static options to operate the chat with.
Human-in-the-loop
Learn how to work with human-in-the-loop to pause the chat and wait for a human to respond.
Reference
Reference documentation for the useCopilotChatHeadless_c hook.
Getting started
Create a new application
Create a CopilotKit app that runs its own
Copilot Runtime. Do not scaffold it with
npx copilotkit@latest create, because that command creates a cloud-hosted
project with no license key.
Then get a free public license key from the sign-up card at the top of this page.
Wire your CopilotKit provider with a license key
Wrap your root layout with CopilotKit and pass in your public license key:
<CopilotKit publicLicenseKey="your-free-public-license-key">
{children}
</CopilotKit>Build a headless chat component
Use useCopilotChatHeadless_c to access messages, a send function, and loading state, then wire them to your own UI:
"use client";
import { useState } from "react";
import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
export default function Home() {
const { messages, sendMessage, isLoading } = useCopilotChatHeadless_c();
const [input, setInput] = useState("");
const handleSend = () => {
if (input.trim()) {
sendMessage({
id: Date.now().toString(),
role: "user",
content: input,
});
setInput("");
}
};
return (
<div>
<h1>My Headless Chat</h1>
<div>
{messages.map((message) => (
<div key={message.id}>
<strong>{message.role === "user" ? "You" : "Assistant"}:</strong>
<p>{message.content}</p>
</div>
))}
{isLoading && <p>Assistant is typing...</p>}
</div>
<div>
<input
value={input}
onChange={(e) => setInput(e.target.value)}
onKeyDown={(e) => e.key === "Enter" && handleSend()}
placeholder="Type your message here..."
/>
<button onClick={handleSend} disabled={isLoading}>
Send
</button>
</div>
</div>
);
}Working with generative UI
You can render generative UI either via useFrontendTool / useComponent, or by reading tools and rendering them directly.
With useFrontendTool
Register a frontend tool and attach a render function. CopilotKit inserts your component wherever that tool call appears in the message stream:
import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
import { useFrontendTool } from "@copilotkit/react-core/v2";
export const Chat = () => {
const { messages } = useCopilotChatHeadless_c();
useFrontendTool({
name: "showCustomComponent",
handler: async () => "Foo, Bar, Baz",
render: ({ result, args, status }) => (
<div
style={{
backgroundColor: "red",
padding: "10px",
borderRadius: "5px",
}}
>
<p>Custom component</p>
<p>Result: {result}</p>
<p>Args: {JSON.stringify(args)}</p>
<p>Status: {status}</p>
</div>
),
});
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.role === "user" ? "User: " : "Assistant: "}
{message.content}
{message.role === "assistant" && message.generativeUI?.()}
</div>
))}
</div>
);
};With raw tool-call data
If you don't want to use useFrontendTool, render the raw data directly:
import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
export const Chat = () => {
const { messages } = useCopilotChatHeadless_c();
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.role === "assistant" &&
message.toolCalls?.map((toolCall) => (
<p key={toolCall.id}>
{toolCall.function.name}: {toolCall.function.arguments}
</p>
))}
</div>
))}
</div>
);
};Working with suggestions
CopilotKit's suggestions give users a list of generated or static prompts. The headless hook exposes full control over the lifecycle.
Generating suggestions
Use useCopilotChatSuggestions to generate and display prompt suggestions in your headless UI:
import {
useCopilotChatHeadless_c,
useCopilotChatSuggestions,
} from "@copilotkit/react-core";
import { useEffect } from "react";
export const Chat = () => {
useCopilotChatSuggestions({
instructions:
"Suggest 5 interesting activities for programmers to do on their next vacation",
maxSuggestions: 5,
});
const { suggestions, generateSuggestions, sendMessage } =
useCopilotChatHeadless_c();
useEffect(() => {
generateSuggestions();
}, []);
return (
<div>
{suggestions.map((s, i) => (
<button
key={i}
onClick={() =>
sendMessage({
id: Date.now().toString(),
role: "user",
content: s.message,
})
}
>
{s.title}
</button>
))}
</div>
);
};Programmatic suggestions
If you want deterministic control, set suggestions manually:
const { suggestions, setSuggestions } = useCopilotChatHeadless_c();
useEffect(() => {
setSuggestions([
{ title: "Suggestion 1", message: "The actual message for suggestion 1" },
{ title: "Suggestion 2", message: "The actual message for suggestion 2" },
]);
}, []);Working with human-in-the-loop
Human-in-the-loop (HITL) pauses the chat and waits for the user's input. It comes in two flavors: tool-based and interrupt-based (certain frameworks only). This section shows the tool-based flow. For interrupt-based HITL, read the interrupt value in the useCopilotChatHeadless_c reference.
Tool-based
Tool-based HITL pauses tool execution until the user responds. The response becomes the tool's result.
import { useState } from "react";
import { useCopilotChatHeadless_c } from "@copilotkit/react-core";
import { ToolCallStatus, useHumanInTheLoop } from "@copilotkit/react-core/v2";
const NameForm = ({ defaultName, onSubmit }) => {
const [name, setName] = useState(defaultName || "");
return (
<div>
<input
value={name}
onChange={(e) => setName(e.target.value)}
placeholder="Enter your name"
/>
<button onClick={() => onSubmit?.(name)}>Submit</button>
</div>
);
};
export const Chat = () => {
const { messages } = useCopilotChatHeadless_c();
useHumanInTheLoop({
name: "getName",
render: ({ respond, args, status }) => {
if (status === ToolCallStatus.Complete) return <div>Name retrieved…</div>;
// `respond` resolves the pending tool call, so call it only on submit.
// Editing the field must not complete the turn on the first keystroke.
return <NameForm defaultName={args.name} onSubmit={respond} />;
},
});
return (
<>
{messages.map((message) => (
<div key={message.id}>
{message.role === "user" ? "User: " : "Assistant: "}
{message.content}
{message.role === "assistant" && message.generativeUI?.()}
</div>
))}
</>
);
};How is this guide?