# Headless UI

> Build your own React Native chat, or a screen that isn't a chat, on CopilotKit's hooks.

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

A headless UI gives you **full control** over the chat experience. You bring your own views, layout, and styles. CopilotKit handles agent communication, message state, tool-call rendering, and streaming. You compose your screens from the low-level hooks, with no prebuilt chat.

On React Native, this is the main way to build a chat. `@copilotkit/react-native/headless` has the provider and every hook, and it needs no native peer dependencies.

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

Use headless UI when:

- The props of the [prebuilt chat](/react-native/claude-sdk-typescript/prebuilt-components) can't give you the layout or the look you need.
- You're adding chat to an app that already has its own components and patterns.
- You're building a screen that talks to an agent but isn't a chat, such as a dashboard or a form.
- You want to render tool calls or agent state outside a chat.

## The core hooks [#the-core-hooks]

Three hooks power it. The prebuilt chat from `/components` uses the same ones.

- `useAgent({ agentId })`: the agent, with its `messages`, `state`, and `isRunning`.
- `useCopilotKit()`: the CopilotKit core. You call `runAgent({ agent })` and `stopAgent({ agent })` on it.
- `useRenderToolCall()`: a function that renders any registered tool call as a React Native element.

## Minimal example [#minimal-example]

The [quickstart](/react-native/claude-sdk-typescript/quickstart) builds the smallest version: a `FlatList` of user and assistant text, a `TextInput`, and a send button that calls `agent.addMessage` and `copilotkit.runAgent`. You get text only. Tool calls do not show until you render them yourself.

## Complete example [#complete-example]

This chat shows text, tool calls with their results, and starter suggestions. It also has a stop button.

```tsx title="src/ChatScreen.tsx"
import { useState } from "react";
import {
  FlatList,
  KeyboardAvoidingView,
  Platform,
  Pressable,
  Text,
  TextInput,
  View,
} from "react-native";
import {
  useAgent,
  useCopilotKit,
  useRenderToolCall,
  useSuggestions,
  type Message,
  type ToolCall,
  type ToolMessage,
} from "@copilotkit/react-native/headless";

type Row =
  | { kind: "text"; id: string; role: "user" | "assistant"; text: string }
  | { kind: "tool"; id: string; toolCall: ToolCall };

// One row per text message and one per tool call.
function toRows(messages: Message[]): Row[] {
  const rows: Row[] = [];
  for (const message of messages) {
    if (message.role === "user" && typeof message.content === "string") {
      rows.push({ kind: "text", id: message.id, role: "user", text: message.content });
    }
    if (message.role === "assistant") {
      if (message.content) {
        rows.push({ kind: "text", id: message.id, role: "assistant", text: message.content });
      }
      for (const toolCall of message.toolCalls ?? []) {
        rows.push({ kind: "tool", id: `${message.id}:${toolCall.id}`, toolCall });
      }
    }
  }
  return rows;
}

export function ChatScreen() {
  const { copilotkit } = useCopilotKit();
  const { agent } = useAgent({ agentId: "default" });
  const renderToolCall = useRenderToolCall(); // [!code highlight]
  const { suggestions } = useSuggestions({ agentId: "default" });
  const [input, setInput] = useState("");

  // Rebuilt on every render: useAgent re-renders this screen on each change.
  const rows = toRows(agent.messages);
  const toolResults = new Map<string, ToolMessage>();
  for (const message of agent.messages) {
    if (message.role === "tool") toolResults.set(message.toolCallId, message);
  }

  const send = async (text: string) => {
    if (!text.trim() || agent.isRunning) return;
    setInput("");
    agent.addMessage({ id: `user-${Date.now()}`, role: "user", content: text });
    try {
      await copilotkit.runAgent({ agent });
    } catch (error) {
      console.error("runAgent failed", error);
    }
  };

  return (
    <KeyboardAvoidingView
      style={{ flex: 1 }}
      behavior={Platform.OS === "ios" ? "padding" : "height"}
    >
      <FlatList
        data={rows}
        keyExtractor={(row) => row.id}
        contentContainerStyle={{ padding: 12, gap: 8 }}
        renderItem={({ item }) => {
          if (item.kind === "tool") {
            return ( // [!code highlight:7]
              renderToolCall({
                toolCall: item.toolCall,
                toolMessage: toolResults.get(item.toolCall.id),
              }) ?? <Text style={{ color: "#888" }}>Called {item.toolCall.function.name}</Text>
            );
          }
          return (
            <View
              style={{
                alignSelf: item.role === "user" ? "flex-end" : "flex-start",
                backgroundColor: item.role === "user" ? "#4f46e5" : "#f1f1f4",
                borderRadius: 16,
                padding: 12,
                maxWidth: "80%",
              }}
            >
              <Text style={{ color: item.role === "user" ? "#fff" : "#111" }}>{item.text}</Text>
            </View>
          );
        }}
        ListEmptyComponent={
          <View style={{ gap: 8 }}>
            {suggestions.map((suggestion) => (
              <Pressable key={suggestion.title} onPress={() => send(suggestion.message)}>
                <Text>{suggestion.title}</Text>
              </Pressable>
            ))}
          </View>
        }
      />
      <View style={{ flexDirection: "row", gap: 8, padding: 8 }}>
        <TextInput
          style={{ flex: 1, borderWidth: 1, borderRadius: 8, padding: 8 }}
          value={input}
          onChangeText={setInput}
          placeholder="Type a message..."
        />
        {agent.isRunning ? (
          <Pressable onPress={() => copilotkit.stopAgent({ agent })}>
            <Text>Stop</Text>
          </Pressable>
        ) : (
          <Pressable onPress={() => send(input)}>
            <Text>Send</Text>
          </Pressable>
        )}
      </View>
    </KeyboardAvoidingView>
  );
}
```

How the pieces fit:

- **Rows.** An assistant message can carry text, tool calls, or both. `toRows` gives each tool call its own row, so the list can draw it where it happened.
- **Tool calls.** For each call, the chat looks up the `tool` message whose `toolCallId` matches, and hands both to `renderToolCall`. The renderer gets the parsed arguments, a live `status`, and the result once it arrives. `renderToolCall` returns `null` when no renderer is registered for that tool, so the sample shows a small fallback line.
- **Suggestions.** `useSuggestions` returns the prompts that `useConfigureSuggestions` set up. Configure them once, anywhere under the provider:

  ```tsx
  useConfigureSuggestions({
    suggestions: [
      { title: "Plan my day", message: "Plan my day around my calendar." },
      { title: "What's due?", message: "Which tasks are due this week?" },
    ],
  });
  ```

- **Ids.** The polyfills give Hermes `crypto.getRandomValues`, not `crypto.randomUUID`, so the sample builds message ids from a timestamp.

Register the renderers that `renderToolCall` draws with `useFrontendTool`, `useRenderTool`, `useComponent`, or `useHumanInTheLoop`. See [Tool Call Rendering](/react-native/claude-sdk-typescript/generative-ui/tool-rendering).

To check it, register a renderer for one of your agent's tools and ask for something that calls it. The tool card renders in your own list, between your own bubbles.

## Markdown [#markdown]

Agents often answer in markdown. A plain `Text` shows it as-is. To render it, use `CopilotMarkdown` from `/components`, or any React Native markdown library. See [Markdown Rendering](/react-native/claude-sdk-typescript/custom-look-and-feel/markdown).

## Interrupts and approvals [#interrupts-and-approvals]

A headless chat also places the interrupt UI itself. Call `useInterrupt` with `renderInChat: false`, and render the element it returns, for example as the list's `ListFooterComponent`. See [Headless Interrupts](/react-native/claude-sdk-typescript/human-in-the-loop/headless). To answer a pause from a button, see [Programmatic Control](/react-native/claude-sdk-typescript/programmatic-control).
