# 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](/reference/react-native/components/CopilotKitProvider), 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](https://docs.ag-ui.com) agent protocol, with no DOM, CSS, or web framework dependencies.

<Callout type="info">
  The package root **is** the v2 API. Unlike the [web SDK](/reference/v2), which exposes v2
  under a `/v2` subpath, React Native exports the v2 surface directly from
  `@copilotkit/react-native`.
</Callout>

## Installation [#installation]

New to CopilotKit on React Native? Start with the [React Native quickstart](/react-native).

```sh
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-native` needs `expo-document-picker` and `expo-file-system`. The root re-exports `useAttachments`, which imports both, and Metro resolves them at bundle time.
- The prebuilt UI in `@copilotkit/react-native/components` also needs `@gorhom/bottom-sheet`, `react-native-gesture-handler`, `react-native-reanimated`, and `react-native-streamdown`.

```sh
npm install \
  expo-document-picker \
  expo-file-system \
  @gorhom/bottom-sheet \
  react-native-gesture-handler \
  react-native-reanimated \
  react-native-streamdown
```

If 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 [#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:

```js title="index.js"
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 [#provider-setup]

Wrap your app (or a sub-tree) with [`CopilotKitProvider`](/reference/react-native/components/CopilotKitProvider) to configure the runtime connection:

```tsx
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 [#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`](/reference/react-native/components/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`](/reference/react-native/components/CopilotChat) and [`CopilotModal`](/reference/react-native/components/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`](/reference/react-native/components/CopilotChat#prebuilt-ui), a bottom-sheet [`CopilotModal`](/reference/react-native/components/CopilotModal#prebuilt-ui), [`CopilotMarkdown`](/reference/react-native/components/CopilotMarkdown), and [message bubbles](/reference/react-native/components/AssistantMessage). |

The root also exports two prebuilt chrome components: [`CopilotSidebar`](/reference/react-native/components/CopilotSidebar) (a slide-in drawer) and [`CopilotPopup`](/reference/react-native/components/CopilotPopup) (a floating action button + overlay).

<Callout type="info">
  `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.
</Callout>

## Generative UI [#generative-ui]

`@copilotkit/react-native/generative-ui` (experimental) lets the agent render a catalog of your own native components: [`GenerativeUIProvider`](/reference/react-native/components/GenerativeUIProvider) turns it on, [`GenerativeUIActivity`](/reference/react-native/components/GenerativeUIActivity) renders a surface from an activity message, and [`GenerativeUISurface`](/reference/react-native/components/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](/react-native#generative-ui-with-your-own-components).

## API Reference [#api-reference]

<Cards>
  <Card
    title="Components"
    description="Provider, headless primitives, prebuilt UI, and generative UI: CopilotKitProvider, CopilotChat, CopilotModal, CopilotSidebar, CopilotPopup, message components, GenerativeUIProvider, GenerativeUIActivity, and GenerativeUISurface."
    href="/reference/react-native/components/CopilotKitProvider"
  />
  <Card
    title="Hooks"
    description="Native attachments and tool rendering plus the platform-agnostic hooks re-exported from react-core: useAgent, useFrontendTool, useHumanInTheLoop, and more."
    href="/reference/react-native/hooks/useAgent"
  />
</Cards>
