Prebuilt Components
Drop-in React Native chat surfaces, from a full-screen chat to a bottom sheet, a popup, and a drawer.
Prebuilt components for agentic chat
@copilotkit/react-native ships two kinds of prebuilt pieces:
- A rendered chat, from
@copilotkit/react-native/components.CopilotChatdraws the message list, the composer, a header, tool calls, and interrupts.CopilotModalputs the same chat in a bottom sheet. - Chrome for your own chat, from
@copilotkit/react-native.CopilotPopupdraws a floating button and a modal card.CopilotSidebardraws a drawer that slides in from the right. Both draw the frame only. You put your chat UI inside them.
| Component | Import | What it draws | Native peers |
|---|---|---|---|
CopilotChat | /components | A full-screen chat | @gorhom/bottom-sheet, react-native-gesture-handler, react-native-reanimated, react-native-streamdown |
CopilotModal | /components | The same chat in a bottom sheet | Same as above |
CopilotPopup | root | A floating button and a modal card around your chat UI | expo-document-picker, expo-file-system |
CopilotSidebar | root | A right-side drawer around your chat UI | expo-document-picker, expo-file-system |
Metro resolves every peer of a surface when you import from it, even peers of components you don't use. See Import surfaces. Follow each library's own setup guide. For example, react-native-streamdown has peers of its own and a required react-native-worklets setup, described in its installation guide.
Two components named CopilotChat
The root CopilotChat and CopilotModal draw nothing. They give an agent to their children through useCopilotChatContext. The ones that draw a chat come from @copilotkit/react-native/components. If you get a blank screen, check the import path.
The customization ladder
Start at the top and step down only when you need more control.
- Drop in the rendered chat. Render
CopilotChatorCopilotModalfrom/components. Streaming, tool calls, and interrupts are wired up. - Adjust it with props. Set the header title, the placeholder, the empty state, starter prompts, and container styles.
- Put your own chat in the chrome. Render your UI inside
CopilotPopuporCopilotSidebar, and read the conversation withuseCopilotChatContext. - Go fully headless. Build any layout from
useAgent,useCopilotKit, anduseRenderToolCall. See Headless UI.
Drop-in chat
Wrap your app in CopilotKitProvider and render CopilotChat from /components. The provider from /headless installs the polyfills. The /components entry relies on it for that.
import { CopilotKitProvider } from "@copilotkit/react-native/headless";
import { CopilotChat } from "@copilotkit/react-native/components";
// See the quickstart for emulator and device hosts.
const runtimeUrl = "http://localhost:8200/api/copilotkit";
export default function App() {
return (
<CopilotKitProvider runtimeUrl={runtimeUrl}>
<CopilotChat
agentName="default"
headerTitle="Assistant"
placeholder="Ask me anything..."
emptyStateTitle="How can I help?"
initialMessages={["What can you do?", "Summarize my tasks"]}
/>
</CopilotKitProvider>
);
}What the rendered chat does:
- It picks its agent with
agentName, notagentId. The default is"default". - It shows
initialMessagesas tappable prompts while the conversation is empty. A tap sends that text. - It draws each tool call with the renderer that
useFrontendTool,useRenderTool,useComponent, oruseHumanInTheLoopregistered. A call with no renderer shows as a short "Called: tool_name" line. - It draws the element from
useInterruptafter the last message. - It shows an error line above the composer when a run fails.
It does not show attachments, and it does not read useConfigureSuggestions. For those, build your own chat. See Multimodal Attachments and Headless UI.
Adjust the look with props
The rendered chat takes three style props: style for the outer container, messageContainerStyle for the message list, and inputContainerStyle for the composer bar. showHeader={false} hides the header. The message bubbles have fixed colors. To change them, render your own bubbles in a headless chat.
<CopilotChat
showHeader={false}
style={{ backgroundColor: "#fafafa" }}
messageContainerStyle={{ paddingHorizontal: 24 }}
inputContainerStyle={{ borderTopWidth: 0 }}
/>Bottom sheet
CopilotModal from /components opens the rendered chat in a @gorhom/bottom-sheet. Open it with a ref, or control it with the visible prop. The bottom sheet needs GestureHandlerRootView from react-native-gesture-handler at the root of your app.
import { useRef } from "react";
import { Button } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { CopilotKitProvider } from "@copilotkit/react-native/headless";
import {
CopilotModal,
type CopilotModalRef,
} from "@copilotkit/react-native/components";
const runtimeUrl = "http://localhost:8200/api/copilotkit";
export default function App() {
const modalRef = useRef<CopilotModalRef>(null);
return (
<GestureHandlerRootView style={{ flex: 1 }}>
<CopilotKitProvider runtimeUrl={runtimeUrl}>
<Button title="Ask the assistant" onPress={() => modalRef.current?.open()} />
<CopilotModal
ref={modalRef}
agentName="default"
headerTitle="Assistant"
snapPoints={["50%", "90%"]}
/>
</CopilotKitProvider>
</GestureHandlerRootView>
);
}Swipe down or tap the backdrop to close the sheet. onDismiss fires when it closes.
Popup and drawer around your own chat
CopilotPopup and CopilotSidebar come from the package root. Each one shows a floating chat button, then opens a frame with a header and a close button. Inside the frame, they mount the root CopilotChat, so your children read the conversation with useCopilotChatContext:
import { useState } from "react";
import { FlatList, Text, TextInput, TouchableOpacity, View } from "react-native";
import { CopilotPopup, useCopilotChatContext } from "@copilotkit/react-native";
function PopupChat() {
const { messages, isRunning, submitMessage } = useCopilotChatContext();
const [text, setText] = useState("");
return (
<View style={{ flex: 1 }}>
<FlatList
data={messages.filter(
(m) => (m.role === "user" || m.role === "assistant") && typeof m.content === "string" && m.content,
)}
keyExtractor={(m) => m.id}
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 || !text.trim()}
onPress={() => {
void submitMessage(text);
setText("");
}}
style={{ padding: 8 }}
>
<Text>Send</Text>
</TouchableOpacity>
</View>
</View>
);
}
export function AssistantPopup() {
return (
<CopilotPopup agentId="default" headerTitle="Assistant" height="70%">
<PopupChat />
</CopilotPopup>
);
}Render AssistantPopup as the last child of a screen's root view that has flex: 1. The button floats in the bottom-right corner.
CopilotSidebar works the same way. It takes width (a number, or a percentage such as "85%") in place of height. It draws the drawer above the screen with absolute positioning, so render it as the last child of the screen's root view too.
Both components take a ref with open(), close(), and toggle(), for your own button. Set showToggleButton={false} to hide the floating button. Pass attachments to turn on file picking for the inner chat. See Multimodal Attachments.
Tool calls and interrupts in your own chat UI
The root CopilotChat inside the popup and the drawer does not draw tool calls or interrupts. Render them in your list with useRenderToolCall, and place the useInterrupt element yourself with renderInChat: false. See Headless UI.
Which surface?
CopilotChat: a full screen or a pane that fills its container.CopilotModal: a bottom sheet over any screen.CopilotPopup: a floating button and a modal card, with your own chat inside.CopilotSidebar: a slide-in drawer, with your own chat inside.
How is this guide?