# Headless UI

> Build any UI (chat or not) on top of the CopilotKit primitives with zero UI opinions.

> **Not available for agent-spec yet.** The code on this page comes from the showcase's `headless-complete` demo, and agent-spec doesn't have it yet. See this page for [CopilotKit's Built-in Agent](/custom-look-and-feel/headless-ui), [LangGraph (Python)](/langgraph-python/custom-look-and-feel/headless-ui), [LangGraph (TypeScript)](/langgraph-typescript/custom-look-and-feel/headless-ui).

## What is this? [#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? [#when-should-i-use-this]

Use headless UI when:

- The [slot system](/agent-spec/custom-look-and-feel/slots) 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` / `useRenderActivityMessage` on their own.
- You want to render generative UI primitives outside of a chat entirely.

## The core hooks [#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 call `runAgent({ agent })` on.
- `useRenderToolCall()`: returns a function that renders any registered tool call inline.

## Minimal example [#minimal-example]

Start with a hand-rolled message list and composer built from `useAgent` + `useCopilotKit`:

> **Not available for agent-spec yet.** This sample comes from the showcase's `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.** This sample comes from the showcase's `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 [#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-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 via `useRenderTool` / `useComponent`, plus the wildcard from `useDefaultRenderTool`).
- `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 [#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 [#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 [#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](/agent-spec/programmatic-control). It shows how to resolve a pause from a button on each kind of framework.
