CopilotChat.mdx

title	CopilotChat
description	Headless chat primitive that wires an agent into context, plus a prebuilt full-screen chat UI from the /components subpath.

Overview

CopilotChat connects an agent and exposes its conversation state to descendants. There are two versions, chosen by import path:

• Headless (@copilotkit/react-native) renders no UI. It wires up useAgent, manages attachments, and exposes everything through useCopilotChatContext so you build the interface from React Native views.
• Prebuilt UI (@copilotkit/react-native/components) is a ready-made full-screen chat with a message list, input bar, and optional header. See Prebuilt UI.

Headless CopilotChat

import { CopilotChat, useCopilotChatContext } from "@copilotkit/react-native";

Props

ID of the agent to connect to. Resolution order: `agentId` → `agentName` → `"default"`. **Deprecated.** Use `agentId`. Kept for backwards compatibility. Thread ID for this chat session. When provided, the chat resumes the specified thread instead of starting a new one. Error handler scoped to this chat's agent. Fires in addition to the provider-level `onError` (does not suppress it), receiving only errors whose `context.agentId` matches this chat's agent. Throttle interval (ms) for re-renders triggered by message changes. Overrides the provider's `defaultThrottleMs`. Enable and configure multimodal file attachments. Children read attachment state and actions from [`useCopilotChatContext`](#usecopilotchatcontext). See [`useAttachments`](/reference/react-native/hooks/useAttachments). Your chat UI. Render React Native views that consume [`useCopilotChatContext`](#usecopilotchatcontext).

useCopilotChatContext

Call inside a <CopilotChat> tree to read the conversation state and actions. Throws if called outside a <CopilotChat>.

function useCopilotChatContext(): CopilotChatContextValue;

The resolved agent instance. Whether the agent is currently running. The current conversation messages. Currently selected attachments (uploading + ready). Whether attachments are enabled for this chat. Open the native document picker to add files. Remove an attachment by ID. Submit a message. Consumes ready attachments, builds the message content, adds the user message, and runs the agent.

Usage

import { CopilotChat, useCopilotChatContext } from "@copilotkit/react-native";
import { useState } from "react";
import { FlatList, Text, TextInput, TouchableOpacity, View } from "react-native";

function ChatUI() {
  const { messages, isRunning, submitMessage } = useCopilotChatContext();
  const [text, setText] = useState("");

  return (
    <View style={{ flex: 1 }}>
      <FlatList
        data={messages.filter((m) => m.content)}
        keyExtractor={(m, i) => m.id ?? String(i)}
        renderItem={({ item }) => (
          <Text style={{ padding: 12 }}>{item.content}</Text>
        )}
      />
      <View style={{ flexDirection: "row", padding: 8 }}>
        <TextInput
          style={{ flex: 1, borderWidth: 1, borderRadius: 8, padding: 8 }}
          value={text}
          onChangeText={setText}
          placeholder="Type a message..."
        />
        <TouchableOpacity
          disabled={isRunning}
          onPress={() => {
            submitMessage(text);
            setText("");
          }}
          style={{ padding: 8 }}
        >
          <Text>Send</Text>
        </TouchableOpacity>
      </View>
    </View>
  );
}

export function ChatScreen() {
  return (
    <CopilotChat agentId="default">
      <ChatUI />
    </CopilotChat>
  );
}

Prebuilt UI

For a ready-made interface, import CopilotChat from the /components subpath. It renders a full-screen chat with a message list, input bar, optional header, and inline tool-call rendering via the render-tool registry.

import { CopilotChat } from "@copilotkit/react-native/components";

Props

The prebuilt UI components select their agent with `agentName` (not the headless `agentId`). The two are equivalent; `agentName` is simply the prop name the prebuilt components currently expose. ID of the agent to connect to. Placeholder text for the input field. Suggestion pills shown in the empty state. Title shown when there are no messages. Subtitle shown when there are no messages. Title for the optional header bar. Whether to show the header bar. Style override for the outermost container. Style override for the message list container. Style override for the input bar container. Callback fired when the user sends a message. Custom list component, for example `BottomSheetFlatList` when nesting inside a bottom sheet. When `true`, skip the `KeyboardAvoidingView` wrapper (useful when a parent already handles the keyboard).

Usage

import { CopilotChat } from "@copilotkit/react-native/components";

export function ChatScreen() {
  return (
    <CopilotChat
      agentName="default"
      headerTitle="Assistant"
      placeholder="Ask me anything..."
      initialMessages={["What's the weather?", "Summarize my tasks"]}
    />
  );
}

Related

• useCopilotKit: access the runtime client directly
• useRenderTool: render React Native UI for agent tool calls
• CopilotModal: modal variants of the chat
• CopilotSidebar · CopilotPopup: prebuilt chrome