# Headless UI

> Build the chat UI yourself with the `useCopilotChatHeadless_c` hook.

<OpsPlatformCTA
  variant="card"
  title="Headless UI requires a CopilotKit Intelligence license key"
  body="Sign up for a free account to get a public license key and unlock the headless hooks."
  ctaLabel="Create a free account"
  surface="docs_intelligence_headless_ui"
/>

## Overview [#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.

<Callout type="warn">
  **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](/built-in-agent/custom-look-and-feel/headless-ui).
</Callout>

## Navigation [#navigation]

<Cards className="gap-6">
  <Card
    icon={<MessageCircleDashed />}
    className="p-6 rounded-xl text-base md:col-span-2"
    title="Getting started"
    description="Build a Headless UI chat from the ground up to get started."
    href="#getting-started"
  />
  <Card
    icon={<Blocks />}
    className="p-6 rounded-xl text-base"
    title="Generative UI"
    description="Learn how to work with generative UI to render tools and other UI elements."
    href="#working-with-generative-ui"
  />
  <Card
    icon={<LayoutList />}
    className="p-6 rounded-xl text-base"
    title="Suggestions"
    description="Learn how to work with suggestions to provide your users with a list of generated or static options to operate the chat with."
    href="#working-with-suggestions"
  />
  <Card
    icon={<UserPen />}
    className="p-6 rounded-xl text-base"
    title="Human-in-the-loop"
    description="Learn how to work with human-in-the-loop to pause the chat and wait for a human to respond."
    href="#working-with-human-in-the-loop"
  />
  <Card
    icon={<BookOpen />}
    className="p-6 rounded-xl text-base"
    title="Reference"
    description="Reference documentation for the useCopilotChatHeadless_c hook."
    href="/reference/v1/hooks/useCopilotChatHeadless_c"
  />
</Cards>

## Getting started [#getting-started]

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/videos/full-headless-chat.mp4"
  className="rounded-xl shadow-lg border"
  loop
  playsInline
  autoPlay
  muted
/>

<Steps>
<Step>
### Create a new application [#create-a-new-application]

Create a CopilotKit app that runs its own
[Copilot Runtime](/langgraph-fastapi/backend/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.
</Step>

<Step>
### Wire your CopilotKit provider with a license key [#wire-your-copilotkit-provider-with-a-license-key]

Wrap your root layout with `CopilotKit` and pass in your public license key:

```tsx title="src/app/layout.tsx"
<CopilotKit publicLicenseKey="your-free-public-license-key">
  {children}
</CopilotKit>
```
</Step>

<Step>
### Build a headless chat component [#build-a-headless-chat-component]

Use `useCopilotChatHeadless_c` to access messages, a send function, and loading state, then wire them to your own UI:

```tsx title="src/app/page.tsx"
"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>
  );
}
```
</Step>
</Steps>

## Working with generative UI [#working-with-generative-ui]

You can render generative UI either via `useFrontendTool` / `useComponent`, or by reading tools and rendering them directly.

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/videos/gen-ui.mp4"
  className="rounded-xl shadow-lg border"
  loop
  playsInline
  autoPlay
  muted
/>

### With `useFrontendTool` [#with-usefrontendtool]

Register a frontend tool and attach a render function. CopilotKit inserts your component wherever that tool call appears in the message stream:

```tsx title="src/app/components/chat.tsx"
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 [#with-raw-tool-call-data]

If you don't want to use `useFrontendTool`, render the raw data directly:

```tsx title="src/app/components/chat.tsx"
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 [#working-with-suggestions]

CopilotKit's suggestions give users a list of generated or static prompts. The headless hook exposes full control over the lifecycle.

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/videos/suggestions.mp4"
  className="rounded-xl shadow-lg border"
  loop
  playsInline
  autoPlay
  muted
/>

### Generating suggestions [#generating-suggestions]

Use `useCopilotChatSuggestions` to generate and display prompt suggestions in your headless UI:

```tsx title="src/app/components/chat.tsx"
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 [#programmatic-suggestions]

If you want deterministic control, set suggestions manually:

```tsx
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 [#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](/reference/v1/hooks/useCopilotChatHeadless_c).

<video
  src="https://cdn.copilotkit.ai/docs/copilotkit/videos/hitl.mp4"
  className="rounded-xl shadow-lg border"
  loop
  playsInline
  autoPlay
  muted
/>

### Tool-based [#tool-based]

Tool-based HITL pauses tool execution until the user responds. The response becomes the tool's result.

```tsx title="src/app/components/chat.tsx"
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>
      ))}
    </>
  );
};
```
