# Fully Headless UI

> Build a Vue surface on CopilotKit’s reactive agent and runtime primitives.

## What is this? [#what-is-this]

A headless UI gives you full control over the experience. You bring your own
components, layout, and styling while CopilotKit handles agent communication,
reactive message state, tool registration, and streaming. No `CopilotChat`
shell is required: your Vue components compose the low-level primitives.

## When should I use this? [#when-should-i-use-this]

Use headless UI when:

- The [slot system](/vue/custom-look-and-feel/slots) is not enough for the
  layout you need.
- You are embedding chat into an existing interface with its own patterns.
- You are building a non-chat surface such as a dashboard, canvas, or
  inspector that still talks to an agent.
- You need direct control over which message roles and registered renderers
  appear.

Going headless also transfers responsibility for the composer, accessibility,
scroll behavior, attachments, reasoning, interrupts, and every message role to
your application, unless you compose the CopilotKit chat components
(`CopilotChatMessageView`, `CopilotChatAssistantMessage`,
`CopilotChatUserMessage`).

## The core composables [#the-core-composables]

These composables provide the same agent and runtime state used by the prebuilt
chat:

- `useAgent({ agentId })` exposes the reactive conversation (`messages`,
  `isRunning`, state, and agent methods).
- `useCopilotKit()` exposes the runtime ref used to call
  `copilotkit.value.runAgent({ agent })`.
- `useRenderActivityMessage()` resolves registered MCP Apps and other custom
  activity renderers for the current agent scope.
- `useRenderCustomMessages()` resolves registered before/after message
  renderers for the active `CopilotChatConfigurationProvider`.

Composables must execute in a component below `CopilotKitProvider`; calling one
above the provider has no injected runtime context.

## Minimal example [#minimal-example]

Start with a text-only message list and composer built from `useAgent` and
`useCopilotKit`:

```vue title="HeadlessChat.vue"
<script setup lang="ts">
import { computed, ref } from "vue";
import { useAgent, useCopilotKit } from "@copilotkit/vue/v2";

const { agent } = useAgent({ agentId: "my-agent" });
const { copilotkit } = useCopilotKit();
const input = ref("");
const messages = computed(() => agent.value?.messages ?? []);
const isRunning = computed(() => agent.value?.isRunning ?? false);

async function submit() {
  const current = agent.value;
  const content = input.value.trim();
  if (!current || !content || isRunning.value) return;

  current.addMessage({
    id: crypto.randomUUID(),
    role: "user",
    content,
  });
  input.value = "";
  await copilotkit.value.runAgent({ agent: current });
}
</script>

<template>
  <section aria-live="polite">
    <article v-for="message in messages" :key="message.id" :data-role="message.role">
      {{ message.content }}
    </article>
    <p v-if="isRunning">Thinking…</p>
    <form @submit.prevent="submit">
      <input v-model="input" aria-label="Message" />
      <button type="submit" :disabled="isRunning">Send</button>
    </form>
  </section>
</template>
```

Render it below the runtime provider and a chat-configuration provider so
agent-scoped custom renderers can resolve consistently:

```vue
<CopilotKitProvider runtime-url="/api/copilotkit">
  <CopilotChatConfigurationProvider agent-id="my-agent">
    <HeadlessChat />
  </CopilotChatConfigurationProvider>
</CopilotKitProvider>
```

Type a message and press **Send**. Your message appears in the list,
"Thinking…" shows while the agent runs, and then the reply appears.

The trade-off is deliberate: this minimal example renders only text. Tool
calls, reasoning messages, activity messages, interrupts, attachments, and
custom before/after content do not appear until you wire them in.

## Complete example [#complete-example]

For a custom outer layout that should retain CopilotKit's complete message
composition, use these chat components rather than rebuilding their state
machines. `CopilotChatMessageView` already dispatches assistant, user,
reasoning, tool, activity, interrupt, and custom before/after content:

```vue title="RenderedMessages.vue"
<script setup lang="ts">
import { computed } from "vue";
import {
  CopilotChatAssistantMessage,
  CopilotChatMessageView,
  CopilotChatUserMessage,
  useAgent,
} from "@copilotkit/vue/v2";

const { agent } = useAgent({ agentId: "my-agent" });
const messages = computed(() => agent.value?.messages ?? []);
const isRunning = computed(() => agent.value?.isRunning ?? false);
</script>

<template>
  <CopilotChatMessageView :messages="messages" :is-running="isRunning">
    <template #assistant-message="assistantProps">
      <article class="assistant-bubble">
        <CopilotChatAssistantMessage v-bind="assistantProps" />
      </article>
    </template>
    <template #user-message="userProps">
      <article class="user-bubble">
        <CopilotChatUserMessage v-bind="userProps" />
      </article>
    </template>
  </CopilotChatMessageView>
</template>
```

### The Vue composition equivalent [#the-vue-composition-equivalent]

`CopilotChatMessageView` is the public component that renders tool calls with
every registered tool renderer. Use it as shown above when your layout needs
those renderers.

### Per-role dispatch [#per-role-dispatch]

If you choose a completely manual renderer, switch on every AG-UI message role:

- Assistant messages contain streamed text and optional tool calls.
- User messages can contain text or multimodal content parts.
- Reasoning messages can use `CopilotChatReasoningMessage`.
- Activity messages can use `useRenderActivityMessage()`.
- Before/after content can use `useRenderCustomMessages()` while inside
  `CopilotChatConfigurationProvider`.
- Interrupts require their own pending-state UI and resolve/cancel action.

Missing a role means that content silently disappears from your custom
surface.

### Tool-call composition [#tool-call-composition]

`CopilotChatMessageView` resolves tool calls in this order: a named
`tool-call-<name>` slot, the `tool-call` fallback slot, then renderers
registered through `useRenderTool` / `useDefaultRenderTool`. Keep
`CopilotChatMessageView` to retain that behavior. A fully manual Vue surface must own its
tool-call rendering because no public resolver composable currently exposes
the registered renderer as a callable function.

### Bubble chrome [#bubble-chrome]

Keep bubble components as pure chrome around these already-rendered chat
components.
That lets your design system own spacing, colors, and layout without copying
the message parsing, toolbar, Markdown, tool-call, or reasoning logic.
