Headless UI
Build any UI (chat or not) on top of the CopilotKit primitives with zero UI opinions.
Not available for agent-spec yet
headless-complete demo, and agent-spec doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).What is this?
A headless UI gives you full control over the chat experience. You bring your own components, layout, and styling while CopilotKit handles agent communication, message management, tool-call rendering, and streaming. No <CopilotChat>, no slot overrides, just your components composed on top of the low-level hooks.
When should I use this?
Use headless UI when:
- The slot system isn't enough: you need a completely different layout.
- You're embedding chat into an existing UI with its own patterns.
- You're building a non-chat surface that still talks to an agent (a dashboard, a canvas, an inspector) and want
useRenderToolCall/useRenderActivityMessageon their own. - You want to render generative UI primitives outside of a chat entirely.
The core hooks
Three hooks power it, and they're the same ones <CopilotChat> uses internally.
useAgent({ agentId }): exposes the current conversation (messages,isRunning) and the run-state object.useCopilotKit(): returns the runtime handle you callrunAgent({ agent })on.useRenderToolCall(): returns a function that renders any registered tool call inline.
Minimal example
Start with a hand-rolled message list and composer built from useAgent + useCopilotKit:
Not available for agent-spec yet
headless-simple demo, and agent-spec doesn't have it yet.The message list is a plain .map() over the user and assistant text in agent.messages:
Not available for agent-spec yet
headless-simple demo, and agent-spec doesn't have it yet.This example does not use <CopilotChat /> or slots. The trade-off: you only get text. Tool calls, activity messages, reasoning messages, and custom before/after slots do not show up unless you wire them in yourself. The complete example wires in tool calls and activity messages.
Complete example
The complete example rebuilds the generative-UI composition from the low-level hooks directly, without importing <CopilotChatMessageView>: text, tool calls with their results, and A2UI and MCP Apps activity messages.
The MessageList component
The example's central piece is a MessageList component. It is a manual recreation of what <CopilotChatMessageView> does. MessageList calls useRenderToolCall and useRenderActivityMessage, and indexes tool results by toolCallId:
Two low-level hooks feed it:
useRenderToolCall(): returns the renderer for any registered tool call (per-tool viauseRenderTool/useComponent, plus the wildcard fromuseDefaultRenderTool).useRenderActivityMessage(): renders A2UI + MCP Apps activity messages for the current agent scope.
To add custom before/after slots, also call useRenderCustomMessages(). It invokes the renderCustomMessage hooks registered against the active CopilotChatConfigurationProvider, and renders "before" and "after" slots around each message.
Per-role dispatch
The role-switch mirrors CopilotChatMessageView's renderMessageBlock: assistant bodies get text and tool calls, user bodies get their text content, and activity messages route through renderActivityMessage:
Tool-call composition
For each toolCall on an assistant message, we look up the sibling tool-role message (keyed by toolCallId) and hand both to renderToolCall:
Bubble chrome
The UserBubble and AssistantBubble components are pure chrome: they receive content from MessageList and drop it into a styled container. No chat primitives are imported here:
To check it, ask the agent for the weather in Tokyo, so that it calls a tool. Your own bubble shows the reply, and the tool card renders inside it.
To answer an approval from your own UI, see Programmatic control. It shows how to resolve a pause from a button on each kind of framework.
How is this guide?