ContextQMD
Back to Copilotkit

CopilotChat

showcase/shell-docs/src/content/reference/react-native/components/CopilotChat.mdx

1.60.28.0 KB
Original Source

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

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

Props

<PropertyReference name="agentId" type="string" default='"default"'> ID of the agent to connect to. Resolution order: `agentId` → `agentName` → `"default"`. </PropertyReference> <PropertyReference name="agentName" type="string"> **Deprecated.** Use `agentId`. Kept for backwards compatibility. </PropertyReference> <PropertyReference name="threadId" type="string"> Thread ID for this chat session. When provided, the chat resumes the specified thread instead of starting a new one. </PropertyReference> <PropertyReference name="onError" type="(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>"> 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. </PropertyReference> <PropertyReference name="throttleMs" type="number"> Throttle interval (ms) for re-renders triggered by message changes. Overrides the provider's `defaultThrottleMs`. </PropertyReference> <PropertyReference name="attachments" type="NativeAttachmentsConfig"> Enable and configure multimodal file attachments. Children read attachment state and actions from [`useCopilotChatContext`](#usecopilotchatcontext). See [`useAttachments`](/reference/react-native/hooks/useAttachments). </PropertyReference> <PropertyReference name="children" type="ReactNode"> Your chat UI. Render React Native views that consume [`useCopilotChatContext`](#usecopilotchatcontext). </PropertyReference>

useCopilotChatContext

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

tsx
function useCopilotChatContext(): CopilotChatContextValue;
<PropertyReference name="agent" type="AbstractAgent"> The resolved agent instance. </PropertyReference> <PropertyReference name="isRunning" type="boolean"> Whether the agent is currently running. </PropertyReference> <PropertyReference name="messages" type="Message[]"> The current conversation messages. </PropertyReference> <PropertyReference name="attachments" type="Attachment[]"> Currently selected attachments (uploading + ready). </PropertyReference> <PropertyReference name="attachmentsEnabled" type="boolean"> Whether attachments are enabled for this chat. </PropertyReference> <PropertyReference name="openPicker" type="() => Promise<void>"> Open the native document picker to add files. </PropertyReference> <PropertyReference name="removeAttachment" type="(id: string) => void"> Remove an attachment by ID. </PropertyReference> <PropertyReference name="submitMessage" type="(text: string) => Promise<void>"> Submit a message. Consumes ready attachments, builds the message content, adds the user message, and runs the agent. </PropertyReference>

Usage

tsx
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.

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

Props

<Callout type="info"> 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. </Callout> <PropertyReference name="agentName" type="string" default='"default"'> ID of the agent to connect to. </PropertyReference> <PropertyReference name="placeholder" type="string"> Placeholder text for the input field. </PropertyReference> <PropertyReference name="initialMessages" type="string[]" default="[]"> Suggestion pills shown in the empty state. </PropertyReference> <PropertyReference name="emptyStateTitle" type="string"> Title shown when there are no messages. </PropertyReference> <PropertyReference name="emptyStateSubtitle" type="string"> Subtitle shown when there are no messages. </PropertyReference> <PropertyReference name="headerTitle" type="string"> Title for the optional header bar. </PropertyReference> <PropertyReference name="showHeader" type="boolean" default="true"> Whether to show the header bar. </PropertyReference> <PropertyReference name="style" type="ViewStyle"> Style override for the outermost container. </PropertyReference> <PropertyReference name="messageContainerStyle" type="ViewStyle"> Style override for the message list container. </PropertyReference> <PropertyReference name="inputContainerStyle" type="ViewStyle"> Style override for the input bar container. </PropertyReference> <PropertyReference name="onSendMessage" type="(text: string) => void"> Callback fired when the user sends a message. </PropertyReference> <PropertyReference name="FlatListComponent" type="React.ComponentType<any>" default="FlatList"> Custom list component, for example `BottomSheetFlatList` when nesting inside a bottom sheet. </PropertyReference> <PropertyReference name="disableKeyboardAvoiding" type="boolean" default="false"> When `true`, skip the `KeyboardAvoidingView` wrapper (useful when a parent already handles the keyboard). </PropertyReference>

Usage

tsx
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"]}
    />
  );
}