ContextQMD
Back to Copilotkit

CopilotKitProvider

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

1.68.14.6 KB
Original Source

Overview

CopilotKitProvider is the React Native provider for CopilotKit. Wrap your app (or the sub-tree that needs a copilot) with it to configure the runtime connection. Every hook and component below it reads the configured client from context.

Importing the package auto-installs the polyfills CopilotKit needs on Hermes, so you do not have to import them manually before using the provider.

<Callout type="info"> Cloud features (`publicLicenseKey` / license-gated functionality) are not yet supported on React Native. Point `runtimeUrl` at a self-hosted runtime. </Callout>

Import

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

Props

<PropertyReference name="children" type="ReactNode" required> The components rendered within the provider. </PropertyReference> <PropertyReference name="runtimeUrl" type="string" required> URL of the CopilotKit runtime endpoint, e.g. `https://your-server/api/copilotkit`. Use your machine's LAN IP (not `localhost`) when testing on a physical device. </PropertyReference> <PropertyReference name="headers" type="Record<string, string> | (() => Record<string, string>)" default="{}"> Custom headers sent with every runtime request. Pass a function to compute headers lazily (e.g. to attach a fresh auth token). </PropertyReference> <PropertyReference name="credentials" type="RequestCredentials"> Credentials mode for fetch requests (e.g. `"include"` for HTTP-only cookies in cross-origin requests). </PropertyReference> <PropertyReference name="useSingleEndpoint" type="boolean"> Whether the runtime uses a single-route endpoint. Leave unset to auto-detect. </PropertyReference> <PropertyReference name="properties" type="Record<string, unknown>" default="{}"> Custom properties forwarded to agents on every run (e.g. user metadata or LangGraph Platform `authorization`). </PropertyReference> <PropertyReference name="onError" type="(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>"> Error handler called when CopilotKit encounters an error. Fires for all error types: runtime connection failures, agent errors, and tool errors. If not provided, errors are logged to `console.error`.
tsx
<CopilotKitProvider
  runtimeUrl="https://your-server/api/copilotkit"
  onError={(event) => {
    console.error(`[${event.code}]`, event.error.message, event.context);
  }}
>
  <App />
</CopilotKitProvider>
</PropertyReference> <PropertyReference name="debug" type="DebugConfig"> Enable debug logging for the client-side event pipeline. When `true`, the core instance emits verbose logs. </PropertyReference> <PropertyReference name="defaultThrottleMs" type="number"> Default throttle interval (ms) for `onMessagesChanged` / `onStateChanged` subscriptions. Individual hooks and components can override this with their own `throttleMs`. </PropertyReference>

Usage

tsx
import { CopilotKitProvider } from "@copilotkit/react-native";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { ChatScreen } from "./ChatScreen";

export default function App() {
  return (
    <SafeAreaProvider>
      <CopilotKitProvider runtimeUrl="https://your-server/api/copilotkit">
        <ChatScreen />
      </CopilotKitProvider>
    </SafeAreaProvider>
  );
}

Behavior

  • Auto-polyfills: importing the package installs the Web API polyfills CopilotKit relies on (ReadableStream, TextEncoder, crypto.getRandomValues, DOMException, location) before any CopilotKit code runs.
  • Shared render-tool registry: the provider instantiates the CopilotKit client whose renderer registry is shared with the rest of CopilotKit. Render functions registered by useRenderTool (or useComponent) write into that registry, so useRenderTool and useRenderToolCall work anywhere below the provider — there is no separate RenderToolProvider wrapper.
  • Stable references: header functions and properties are memoized internally to avoid effect churn on re-render.
  • useCopilotKit: access the configured client from any descendant
  • useAgent: connect to an agent and read its state
  • Polyfills: what gets installed and how to bring your own