React Native

@copilotkit/react-native gives you CopilotKit's provider and hooks for React Native, plus optional pre-built chat components. This guide builds a fully custom chat UI with the hooks, backed by a Copilot Runtime endpoint on your server.

The package has three import surfaces — /headless (provider + hooks, no native peer dependencies), the root barrel, and /components (the rendered chat UI). See Import surfaces for what each one pulls in; this guide uses /headless throughout.

Prerequisites#

• An OpenAI API key (or another model provider supported by Model Selection)
• React Native 0.70+ (bare CLI or Expo)
• Node.js 20+

Getting started#

npx @react-native-community/cli@latest init MyCopilotApp
cd MyCopilotApp

npm install @copilotkit/react-native @copilotkit/runtime
npm install -D tsx typescript @types/node

pnpm add @copilotkit/react-native @copilotkit/runtime
pnpm add -D tsx typescript @types/node

yarn add @copilotkit/react-native @copilotkit/runtime
yarn add -D tsx typescript @types/node

npm install react-native-get-random-values

import "react-native-get-random-values"; // secure RNG — must be first
import "@copilotkit/react-native/polyfills";

import { AppRegistry } from "react-native";
import App from "./App";
import { name as appName } from "./app.json";

AppRegistry.registerComponent(appName, () => App);

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";

import { createServer } from "node:http";
import { BuiltInAgent, CopilotRuntime } from "@copilotkit/runtime/v2";
import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";

const runtime = new CopilotRuntime({
  agents: {
    default: new BuiltInAgent({
      model: "openai:gpt-5-mini",
      prompt: "You are a helpful assistant for a React Native app.",
    }),
  },
});

const port = Number(process.env.PORT ?? 8200);

createServer(
  createCopilotNodeListener({
    runtime,
    basePath: "/api/copilotkit",
    cors: true,
  }),
).listen(port, () => {
  console.log(
    `Copilot Runtime listening at http://localhost:${port}/api/copilotkit`,
  );
});

import { CopilotKitProvider } from "@copilotkit/react-native/headless"; 
import { Platform } from "react-native";
import { ChatScreen } from "./src/ChatScreen";

const runtimeUrl =
  Platform.OS === "android"
    ? "http://10.0.2.2:8200/api/copilotkit"
    : "http://localhost:8200/api/copilotkit";

export default function App() {
  return (
    <CopilotKitProvider runtimeUrl={runtimeUrl}> {}
      <ChatScreen />
    </CopilotKitProvider>
  );
}

import { useCallback, useRef, useState } from "react";
import {
  FlatList,
  KeyboardAvoidingView,
  Platform,
  Text,
  TextInput,
  TouchableOpacity,
  View,
} from "react-native";
import { useAgent, useCopilotKit } from "@copilotkit/react-native/headless"; 

export function ChatScreen() {
  const [inputText, setInputText] = useState("");
  const flatListRef = useRef<FlatList>(null);

  const { copilotkit } = useCopilotKit(); 
  const { agent } = useAgent({ agentId: "default" });

  const messages = agent?.messages ?? [];
  const isLoading = agent?.isRunning ?? false;
  const chatMessages = messages.flatMap((message) => {
    if (
(message.role === "user" || message.role === "assistant") &&
      typeof message.content === "string" &&
      message.content.length > 0
    ) {
      return [
        {
          id: message.id,
          content: message.content,
        },
      ];
    }
    return [];
  });

  const handleSend = useCallback(async () => {
    const text = inputText.trim();
if (!text || isLoading || !agent) return;

    setInputText("");
    agent.addMessage({ 
      id: `user-${Date.now()}`,
      role: "user",
      content: text,
    });
    await copilotkit.runAgent({ agent }); 
  }, [inputText, isLoading, agent, copilotkit]);

  return (
    <KeyboardAvoidingView
      style={{ flex: 1 }}
      behavior={Platform.OS === "ios" ? "padding" : "height"}
    >
      <FlatList
        ref={flatListRef}
        data={chatMessages}
        renderItem={({ item }) => (
          <View style={{ padding: 12, maxWidth: "80%" }}>
            <Text>{item.content}</Text>
          </View>
        )}
        keyExtractor={(item, i) => item.id ?? String(i)}
        onContentSizeChange={() =>
          flatListRef.current?.scrollToEnd({ animated: true })
        }
      />
      <View style={{ flexDirection: "row", padding: 8 }}>
        <TextInput
          style={{ flex: 1, borderWidth: 1, borderRadius: 8, padding: 8 }}
          value={inputText}
          onChangeText={setInputText}
          placeholder="Type a message..."
        />
        <TouchableOpacity onPress={handleSend} style={{ padding: 8 }}>
          <Text>Send</Text>
        </TouchableOpacity>
      </View>
    </KeyboardAvoidingView>
  );
}

export OPENAI_API_KEY=sk-...
npx tsx server.ts

npx react-native run-ios

npx react-native run-android

Import surfaces#

@copilotkit/react-native has three JavaScript entry points. They differ in what UI they give you and — crucially for release bundles — which native peer dependencies Metro has to resolve.

Supporting entry points:

Because these are static re-exports, Metro resolves a surface's peers at bundle time whether or not you call the code — so a custom-UI app importing the root barrel must still install expo-document-picker and expo-file-system (or stub them) or the release bundle fails with Unable to resolve module expo-document-picker. Importing from /headless avoids that entirely, which is why this guide uses it:

import {
  CopilotKitProvider,
  useAgent,
  useFrontendTool,
} from "@copilotkit/react-native/headless"; 

Importing the provider auto-installs the polyfills: /headless runs the polyfill barrel as its first statement, and the root barrel gets it through its /headless re-export. /components does not install them itself — it relies on the provider you import alongside it (from /headless or the root). And because the root barrel re-exports everything from /headless, existing @copilotkit/react-native imports keep working unchanged.

Which hooks are shared, and which aren't#

The package (both /headless and the root barrel) re-exports the platform-agnostic hooks from @copilotkit/react-core: useAgent, useFrontendTool, useHumanInTheLoop, useInterrupt, useSuggestions, useConfigureSuggestions, useAgentContext, useThreads, useCapabilities, useComponent, and useCopilotKit. These behave the same as on the web.

Two React-Native-specific differences are worth knowing:

• useRenderTool is React Native's own hook, not react-core's. It registers the tool and its renderer, requires both description and parameters, accepts a handler, and must return ReactElement | null (React Native's FlatList cannot render bare strings). It writes into react-core's canonical renderer registry, so a named renderer draws in the chat exactly as it does on the web — but do not register a "*" entry here. react-core's hook is renderer-only and special-cases "*" into a fallback renderer with no arguments schema; React Native's routes through useFrontendTool, which also calls addTool. So on React Native a "*" entry registers a real frontend tool literally named *, which is advertised to the model in the run's tool list and collides with core's separate wildcard-executable-tool feature — whose handler is invoked for every otherwise-unmatched tool call with arguments wrapped as { toolName, args } rather than in your schema's shape. Register one named renderer per tool instead. See Known limitations.
• Most of the web rendering hooks are deliberately not exported: useDefaultRenderTool (its built-in card renders <div> / <svg>), useRenderCustomMessages, and useRenderActivityMessage (both link the web chat-message stack). useRenderToolCall is exported, though — it is platform-agnostic, pulls no DOM, and returns ReactElement | null, which is exactly what FlatList's renderItem needs, so you can draw a registered tool call on any surface rather than only inside the chat.

Metro configuration for release bundles#

With package exports enabled, a release bundle can fail with Unable to resolve module node:crypto (or another node: specifier) pointing at jose. This surfaces only at bundle time, never at typecheck.

jose is not a direct dependency. It arrives transitively through telemetry: @copilotkit/shared → @segment/analytics-node → jose. jose publishes separate Node and browser builds behind its exports map, and its Node build imports node:-prefixed modules that Hermes cannot bundle.

The fix is to resolve jose specifically against its browser condition, using resolveRequest:

const { getDefaultConfig, mergeConfig } = require("@react-native/metro-config");

const config = {
  resolver: {
    resolveRequest: (context, moduleImport, platform) => {
      // jose reaches the bundle via @copilotkit/shared -> @segment/analytics-node.
      // Its Node build imports node:* modules that Hermes can't bundle.
      if (moduleImport === "jose" || moduleImport.startsWith("jose/")) {
        return context.resolveRequest(
          { ...context, unstable_conditionNames: ["browser"] }, 
          moduleImport,
          platform,
        );
      }
      return context.resolveRequest(context, moduleImport, platform);
    },
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

On Expo, swap in getDefaultConfig from expo/metro-config; the resolver block is identical.

Polyfills#

Hermes lacks several Web APIs CopilotKit relies on: ReadableStream / WritableStream / TransformStream, TextEncoder / TextDecoder, DOMException and Headers, crypto.getRandomValues, and window.location. It also lacks streaming fetch bodies (response.body.getReader()), which AG-UI's SSE transport needs.

Importing the provider installs these automatically: /headless runs the polyfill barrel as its first statement (and the root barrel gets it through /headless), also installing an XHR-based streaming-fetch shim on load. The /components surface does not install them on its own, so it relies on the provider imported alongside it. Each polyfill is skipped if the global it defines already exists, so importing more than once is safe.

Keep the explicit import "@copilotkit/react-native/polyfills" from the quickstart at the top of your entry point anyway. Because every polyfill is first writer wins, the entry point is the only place you control what gets installed before CopilotKit's own defaults do — which is what makes the secure-RNG ordering below work.

For granular control — for example, if you already polyfill ReadableStream yourself — import only the pieces you need instead of the barrel:

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";

import "react-native-get-random-values"; // secure RNG — must be first
import "@copilotkit/react-native/polyfills";
// ...

Provider options#

CopilotKitProvider is a context-only provider (it renders no view of its own), so it composes cleanly as the outermost wrapper around your app. runtimeUrl is the only required prop, but several others are available:

<CopilotKitProvider
  runtimeUrl={runtimeUrl}
  headers={{ Authorization: `Bearer ${token}` }} 
  properties={{ userId }}
>
  <ChatScreen />
</CopilotKitProvider>

const [token, setToken] = useState(initialToken);

<CopilotKitProvider runtimeUrl={runtimeUrl} headers={{ Authorization: `Bearer ${token}` }}>

Runtime and model wiring#

The runtime from the quickstart hosts a BuiltInAgent and serves it with createCopilotNodeListener, which plugs straight into Node's built-in node:http createServer — no Hono or Express dependency required. createCopilotNodeListener({ runtime, basePath, cors }) returns a request listener.

cors: true adds Access-Control-* response headers and answers OPTIONS preflights. That matters for browser clients — Expo Web or react-native-web — but it has no bearing on whether a native iOS or Android build can reach the server: CORS is enforced by the browser, and React Native's native networking stack (NSURLSession / OkHttp) neither sends an Origin header nor consults Access-Control-Allow-Origin. Native reachability is decided by the server's bind address, LAN routing and firewall, and platform transport security — see Connecting from a device or bench.

BuiltInAgent accepts a model string in provider:model (or provider/model) form for OpenAI, Anthropic, and Google:

new BuiltInAgent({ model: "openai:gpt-5-mini", prompt: "..." });      // OPENAI_API_KEY
new BuiltInAgent({ model: "anthropic:claude-sonnet-4.5", prompt: "..." }); // ANTHROPIC_API_KEY
new BuiltInAgent({ model: "google:gemini-2.5-pro", prompt: "..." });  // GOOGLE_API_KEY

The string form reads the matching provider API key from the environment. You can also pass apiKey on the config, or an already-constructed AI SDK LanguageModel instance in place of the string.

OpenAI-compatible endpoints#

To point the string model form at an OpenAI-compatible endpoint (a gateway, Azure OpenAI, a self-hosted server, etc.), set the base-URL environment variable — the runtime honors it when it constructs the provider:

export OPENAI_BASE_URL=https://your-gateway.example.com/v1
export OPENAI_API_KEY=sk-...
npx tsx server.ts

The same applies to ANTHROPIC_BASE_URL and GOOGLE_GENERATIVE_AI_BASE_URL. When the variable is unset, the provider falls back to its default endpoint, so this is fully backward compatible — you do not need to build a custom model instance just to change the base URL.

Connecting from a device or bench#

runtimeUrl must be an address the device can reach — localhost on a physical device or emulator resolves to the device itself, not your dev machine.

The quickstart already branches on Platform.OS for the simulator/emulator case. Keep the URL a single named constant with a comment so it's easy to swap per environment.

Plaintext HTTP on a physical device#

Both platforms block plaintext (non-TLS) HTTP by default, so a device silently fails to reach a plain http://<lan-ip> dev runtime. These are dev-only affordances — a hosted TLS runtime needs none of them.

On Expo, configure both through app.json so they survive the android/ and ios/ regeneration that expo prebuild performs (never hand-edit the generated AndroidManifest.xml or Info.plist — they're discarded on the next prebuild). Install the config plugin first:

npx expo install expo-build-properties

Android — an Android release build needs cleartext opted in:

{
  "expo": {
    "plugins": [
      ["expo-build-properties", { "android": { "usesCleartextTraffic": true } }]
    ]
  }
}

iOS — App Transport Security applies to debug and release builds alike, and expo-build-properties has no iOS ATS option, so this goes in ios.infoPlist. Since iOS 17, ATS refuses raw IP addresses unless the address is listed in NSExceptionDomains, so name your dev machine's IP explicitly (no port):

{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSAppTransportSecurity": {
          "NSExceptionDomains": {
            "192.168.1.23": { "NSExceptionAllowsInsecureHTTPLoads": true }
          }
        },
        "NSLocalNetworkUsageDescription": "Connects to the local Copilot Runtime during development."
      }
    }
  }
}

NSLocalNetworkUsageDescription is required separately: iOS gates local-network access behind a user permission prompt, and without the string the connection fails regardless of ATS.

Frontend tools and generative UI#

Frontend tools let the agent call functions in your app — and render UI — while the model runs. Register them with useFrontendTool. parameters is a Standard Schema, so a zod schema (zod ≥ 3.24 implements Standard Schema) is the expected shape. zod is an optional peer dependency of @copilotkit/react-native, so add it to your app:

import { useFrontendTool } from "@copilotkit/react-native/headless";
import { z } from "zod";

export function useComposeStage() {
  useFrontendTool({
    name: "composeStage",
    description: "Render POI panels on the screen.",
    agentId: "default", // scope the tool to one agent
    parameters: z.object({
      mode: z.enum(["home", "nearby", "hotels"]),
      panels: z.array(
        z.object({ title: z.string(), body: z.string().optional() }),
      ),
    }),
    handler: async (args) => {
      // Runs on the device. Push args into your own state/reducer here.
      return "rendered";
    },
  });
}

Because the tool is registered on the device, the model's call reaches your handler on the client — the ideal place to drive a state reducer that your React Native views render declaratively (the agent sends state, the client owns rendering). Discriminated-union / oneOf / anyOf param schemas are preserved through the runtime's schema conversion, so z.discriminatedUnion(...) params work. It's still good practice to normalize defensively in the handler — coerce a partially populated tool call into valid state rather than letting a malformed one render broken UI.

import { ToolCallStatus, useRenderTool } from "@copilotkit/react-native/headless";

useRenderTool({
  name: "composeStage",
  description: "Render POI panels on the screen.",
  parameters: z.object({ mode: z.string() }),
  render: ({ args, status }) => (
    <StagePreview mode={args.mode} pending={status !== ToolCallStatus.Complete} />
  ),
});

Sending a turn and reading run state#

Running a user turn is the two-step the quickstart shows: agent.addMessage(...) then copilotkit.runAgent({ agent }) (the runner lives on the core, not the agent). To cancel an in-flight run, call copilotkit.stopAgent({ agent }).

When another component needs only the run flag — a "thinking" indicator, say — subscribe with useAgent (a plain read that registers nothing) and read agent.isRunning. Call the tool-registering hook exactly once per agent so a tool isn't registered twice.

Run lifecycle and UI#

A client-executed frontend tool renders its UI mid-run: the tool fires, your handler paints the screen, and the agent's run keeps going (further reasoning, a trailing summary). So agent.isRunning stays true past the moment the content is visible — the more so with a reasoning-tier model. Design run-gated UI around that gap:

• Tie a loading overlay strictly to isRunning (render nothing when it's false) so an errored turn can't leave it stuck on. Keep always-available controls (a home or cancel button) above the overlay so they stay tappable while the run finishes.
• If you gate a reveal animation, trigger it on the falling edge of isRunning (true → false) rather than on the content-arrived state change — otherwise the animation plays while the overlay is still up and the user never sees it.
• Bound the run's tail with maxSteps on the agent so it doesn't linger longer than needed.

Voice and speech-to-text#

@copilotkit/voice has not been adapted for React Native, so there's no drop-in voice hook. Voice is a bring-your-own-STT concern: capture a transcript with a React Native speech recognizer, then feed the final text through the same send-a-turn path (agent.addMessage + copilotkit.runAgent).

Known limitations#

• Markdown in a custom UI — the rendered chat on @copilotkit/react-native/components renders markdown for you (via CopilotMarkdown, backed by react-native-streamdown). If you build your own UI, a plain Text shows markdown as-is — reuse CopilotMarkdown or bring your own renderer.
• Voice — @copilotkit/voice has not been adapted for React Native; wire your own STT as above.
• threadId on useAgent — not supported yet (#6141). Thread scoping comes from a chat-configuration provider; a threadId passed to useAgent does not typecheck and is ignored.
• Cloud provider props — publicApiKey / licenseToken are not supported on the React Native provider; connect via runtimeUrl.
• Web-only rendering hooks — useDefaultRenderTool, useRenderCustomMessages, and useRenderActivityMessage are not exported, because they render host DOM or link the web chat-message stack. useRenderToolCall is exported; use it to draw a registered tool call outside the chat.
• useRenderTool is not react-core's useRenderTool — React Native's hook registers a frontend tool as well as a renderer (it routes through useFrontendTool), and that has three consequences. A "*" name is not a renderer-only wildcard as it is on the web: it registers a frontend tool named * and advertises it to the model, so register named renderers instead. Of the tool-level options useFrontendTool itself accepts, followUp and available are not forwarded, so neither can be set through this hook. And its handler type declares only (args), omitting the context argument (toolCall / agent / signal) that core does pass at runtime, so a typed handler cannot reach it. All three are tracked for a follow-up that converges React Native onto react-core's hooks; until then reach for useFrontendTool directly when you need a tool-level option.

Next steps#

• Model selection: provider strings, keys, and custom endpoints in Model Selection
• Copilot Runtime: hosting and configuring the server in Copilot Runtime
• Agents: what the built-in agent supports in Build with agents