React Native
API reference for @copilotkit/react-native: the headless provider, prebuilt UI components, and hooks for building CopilotKit into a React Native app.
@copilotkit/react-native brings CopilotKit to React Native. It ships a lightweight provider, a set of prebuilt UI components, hooks built for React Native, and re-exports of the platform-agnostic hooks from @copilotkit/react-core. Everything is built on the AG-UI agent protocol, with no DOM, CSS, or web framework dependencies.
The package root is the v2 API. Unlike the web SDK, which exposes v2
under a /v2 subpath, React Native exports the v2 surface directly from
@copilotkit/react-native.
Installation
New to CopilotKit on React Native? Start with the React Native quickstart.
npm install @copilotkit/react-native "zod@^3.25"Every entry of the package needs zod 3.25 or later, because @copilotkit/react-core requires it as a peer dependency. @copilotkit/react-native declares zod an optional peer at >=3.0.0, so the package manager does not enforce 3.25 for you. The command installs zod 3: the child() and childList() helpers of generative UI return zod 3 schemas, which a zod 4 schema cannot hold.
Install the optional peer dependencies:
- Importing from
@copilotkit/react-nativeneedsexpo-document-pickerandexpo-file-system. The root re-exportsuseAttachments, which imports both, and Metro resolves them at bundle time. - The prebuilt UI in
@copilotkit/react-native/componentsalso needs@gorhom/bottom-sheet,react-native-gesture-handler,react-native-reanimated, andreact-native-streamdown.
npm install \
expo-document-picker \
expo-file-system \
@gorhom/bottom-sheet \
react-native-gesture-handler \
react-native-reanimated \
react-native-streamdownIf you build your own UI, import from @copilotkit/react-native/headless instead. That entry has the provider and the hooks, and it needs none of these packages. Neither does @copilotkit/react-native/generative-ui.
Polyfills
React Native's JS runtime (Hermes) lacks several Web APIs that CopilotKit depends on (ReadableStream, TextEncoder, crypto.getRandomValues, DOMException, location). Importing @copilotkit/react-native auto-installs these polyfills, so no manual import is required.
If you bring your own polyfills, import only the pieces you need before any other code in your entry point:
import "@copilotkit/react-native/polyfills/streams";
import "@copilotkit/react-native/polyfills/encoding";
import "@copilotkit/react-native/polyfills/crypto";
import "@copilotkit/react-native/polyfills/dom";
import "@copilotkit/react-native/polyfills/location";Provider setup
Wrap your app (or a sub-tree) with CopilotKitProvider to configure the runtime connection:
import { CopilotKitProvider } from "@copilotkit/react-native";
export default function App() {
return (
<CopilotKitProvider runtimeUrl="https://your-server/api/copilotkit">
<ChatScreen />
</CopilotKitProvider>
);
}Two ways to build the chat UI
The package is organized into two tiers, so you can pick how much UI you write yourself:
| Tier | Import | What you get |
|---|---|---|
| Provider and hooks only | @copilotkit/react-native/headless | CopilotKitProvider and the hooks, with no chat UI and no Expo or bottom-sheet dependencies. |
| Headless | @copilotkit/react-native | Primitives that wire up an agent and expose its state. CopilotChat and CopilotModal render no UI; you build the interface from React Native views. |
| Prebuilt UI | @copilotkit/react-native/components | Drop-in chat UI: a full-screen CopilotChat, a bottom-sheet CopilotModal, CopilotMarkdown, and message bubbles. |
The root also exports two prebuilt chrome components: CopilotSidebar (a slide-in drawer) and CopilotPopup (a floating action button + overlay).
CopilotChat and CopilotModal exist in both tiers with different
props. The root exports are headless; the /components exports are prebuilt
UI. Each component page documents both, disambiguated by import path.
Generative UI
@copilotkit/react-native/generative-ui (experimental) lets the agent render a catalog of your own native components: GenerativeUIProvider turns it on, GenerativeUIActivity renders a surface from an activity message, and GenerativeUISurface marks a named place in your app. It is opt-in: the other entries never import it. It has no theme and no markdown transport, and the built-in openUrl function is not available on React Native. See Generative UI with your own components.
API Reference
Components
Provider, headless primitives, prebuilt UI, and generative UI: CopilotKitProvider, CopilotChat, CopilotModal, CopilotSidebar, CopilotPopup, message components, GenerativeUIProvider, GenerativeUIActivity, and GenerativeUISurface.
Hooks
Native attachments and tool rendering plus the platform-agnostic hooks re-exported from react-core: useAgent, useFrontendTool, useHumanInTheLoop, and more.
How is this guide?