React Native
read as.md@guuey/chat/native is the React Native renderer over the same view-model as the web kit — the plan derivation, policies, presets, strings, and even the React hooks (useTranscript, useTranscriptInputs) are literally the same modules; only the walk differs. Guuey’s own Portal apps (iOS/Android) render their chat through this tier. Its companion, @guuey/chat/native-adapters, supplies the pieces a native chat needs beside the renderer: the adapters useAgentInvoke runs on, and a view slot that mounts generative-UI cards in a WebView.
Both react and react-native are optional peer dependencies. The root @guuey/chat subpath stays importable everywhere, and the native subpaths load only inside a React Native runtime. The packages ship compiled JavaScript, so a stock Expo Metro bundles them with no configuration.
This page describes @guuey/chat 0.32.0 and later (0.34.0 is current). Version 0.31.1 and earlier have no native-adapters subpath and need Metro and Hermes workarounds that this page no longer covers, so upgrade first.
Tested versions
Section titled “Tested versions”The package’s peer ranges are react-native 0.76 or later and react 18 or later. Being in that range is not the same as being tested on it, so here is what Guuey actually runs:
| Stack | Status |
|---|---|
| Expo SDK 55, React Native 0.83, React 19.2 | Tested. Guuey’s Portal app runs on it. Portal renders its chat through @guuey/chat/native, streams with expo/fetch, and mounts generative-UI views on react-native-webview 13 through @ggui-ai/mcp-apps-react-native 0.29.0. |
| React Native 0.76 to 0.82, including Expo SDK 52 to 54 | Allowed, not tested. Inside the peer range, but no Guuey build runs on these versions. |
| React Native earlier than 0.76 | Not supported. Outside the peer range. |
Portal wires its own transport and view component, so it doesn’t run the packaged adapters on a device. They’re covered by the package’s own tests, and Portal’s type check confirms that McpAppIframe from @ggui-ai/mcp-apps-react-native 0.29.0 fits createNativeViewHost as is.
What an older app needs to check is not in the kit itself. The kit uses only core React Native components and ships no native modules. You pass in the two pieces that vary by version:
- A streaming fetch. React Native’s global
fetchreturns no response body stream, so a turn cannot stream through it. Passfetchfromexpo/fetchtocreateNativeAdapters, and confirm your Expo SDK’sexpo/fetchstreams response bodies before you rely on it. - A WebView for the view mount.
createNativeViewHosttakesMcpAppIframefrom@ggui-ai/mcp-apps-react-native, which runs onreact-native-webview13.
Install
Section titled “Install”npx expo install react-native-webview @react-native-async-storage/async-storagenpm install @guuey/chat @guuey/agent-client @ggui-ai/mcp-apps-react-native @modelcontextprotocol/sdk@guuey/chat brings @guuey/agent-client and @guuey/mcp-apps-host at its own version. Install @guuey/agent-client at that same version, since your code imports useAgentInvoke from it. @modelcontextprotocol/sdk is a required peer of @ggui-ai/mcp-apps-react-native, named here because some package managers (yarn classic among them) don’t install peers on their own.
Basic usage
Section titled “Basic usage”import { useMemo } from "react";import { fetch } from "expo/fetch";import AsyncStorage from "@react-native-async-storage/async-storage";import { McpAppIframe } from "@ggui-ai/mcp-apps-react-native";import { useAgentInvoke } from "@guuey/agent-client/react";import { calmPolicy } from "@guuey/chat";import { NativeTranscript, useTranscript, useTranscriptInputs } from "@guuey/chat/native";import { createNativeAdapters, createNativeViewHost } from "@guuey/chat/native-adapters";
const adapters = createNativeAdapters({ fetch, // streaming: the invoke stream and the history read both go through it storage: AsyncStorage, // where the thread id persists apiBaseUrl: "https://api.us-east-1.guuey.com/v1", // enables history on reload getGuestSecret: () => AsyncStorage.getItem("guest-secret"), // or getAccessToken for a signed-in app});
// Create it once: a new slot component per render remounts every card.const view = createNativeViewHost({ McpAppIframe });
export function NativeChatScreen() { const invoke = useAgentInvoke({ endpointUrl: "https://your-agent-endpoint", appId: "your-app-id", adapters, preserveBlocks: true, }); const { inputs } = useTranscriptInputs(invoke); const policy = useMemo(() => calmPolicy(), []); const transcript = useTranscript({ inputs, policy });
return ( <NativeTranscript plan={transcript.plan} strings={policy.strings} onToggle={transcript.toggle} onViewPhase={transcript.onViewPhase} resolvedMounts={transcript.resolvedMounts} components={{ view }} /> );}createNativeAdapters takes the same identity options as createWebAdapters, with the same rules: one identity per request, and a bearer always wins over the guest secret. getGuestSecret may return a promise. A guest secret is 64 lowercase hex characters that your app creates once and keeps. See Give visitors a stable identity. The history adapter is installed when you pass an apiBaseUrl and at least one identity option. The thread id persists in the storage you pass, and storagePrefix gives its keys their own namespace in a shared store. If a write fails, the thread id is kept in memory for the session. The retry options (saturationAttempts, onSaturationWait, coldStartRetry) work as they do on the web. See Resilience defaults. If your runtime has no crypto.randomUUID, pass generateId with a UUID generator.
To use only the thread store, asyncStorageThreadStore(AsyncStorage, { prefix }) returns it on its own.
The scroll contract, inverted
Section titled “The scroll contract, inverted”NativeTranscript renders an inverted list — the chat-app native idiom where content grows at the scroll origin. That makes the transcript scroll contract hold by construction: streaming stays pinned to the latest message, scrolling up never yanks the reader, and a reduce-motion-aware jump-to-latest affordance appears when you’re away from the bottom. Windowing comes from the list primitive itself. Host chrome — keyboard avoidance, docks, insets — passes through a listProps escape hatch rather than being guessed at by the kit.
The view mount is a required override
Section titled “The view mount is a required override”The native tier deliberately ships without a WebView dependency — adding one would force a native module choice on every consumer. So the view slot (generative-UI card mounts) is a required override on native: without one, the kit renders a labeled placeholder (“view unavailable”-style copy) — never a blank. Pass the slot createNativeViewHost builds, as in the sample above, or wrap your app’s WebView of choice as the view component; the display item hands you the resolved mount material and the producing tool’s title.
Mounting MCP Apps views
Section titled “Mounting MCP Apps views”createNativeViewHost takes McpAppIframe from @ggui-ai/mcp-apps-react-native, which runs on react-native-webview and handles each card’s ui/initialize handshake, size reports and tool calls itself. The slot it returns:
- gives the WebView the card’s inline HTML only, never a URL to load
- sizes the frame from the card’s own size reports, starting at 360 points and clamped between 160 and 760 (
initialHeight,minHeightandmaxHeightchange these) - reports the card’s view phase back to the transcript
- shows the kit’s labeled placeholder while a card is still resolving or has expired
- relays the card’s tool calls to the agent through
onUiAction, scoped to that card. WithoutonUiAction, each call is answered in the card as “not available”.
Wiring it in. Read cards that arrive as a ui:// locator with createUiResourceReader, and send a card’s tool calls back through createUiActionRelay; both come from @guuey/agent-client. Give them the same identity your chat uses: guestSecret for an anonymous app, or getAccessToken for a signed-in one.
import { useMemo, useRef } from "react";import { McpAppIframe } from "@ggui-ai/mcp-apps-react-native";import { createUiActionRelay, createUiResourceReader } from "@guuey/agent-client";import { createNativeViewHost } from "@guuey/chat/native-adapters";
const API_BASE_URL = "https://api.us-east-1.guuey.com/v1";
// inside your chat screen, after useAgentInvoke:const threadId = invoke.threadId;const reader = useMemo( () => createUiResourceReader({ apiBaseUrl: API_BASE_URL, endpointUrl: AGENT_URL, guestSecret, // or getAccessToken for a signed-in app ...(threadId ? { threadId } : {}), }), [guestSecret, threadId]);const relay = useRef<ReturnType<typeof createUiActionRelay> | null>(null);relay.current = threadId ? createUiActionRelay({ apiBaseUrl: API_BASE_URL, threadId, endpointUrl: AGENT_URL, guestSecret }) : null;
const transcript = useTranscript({ inputs, policy, reader });// Create it once: a new slot component would remount every WebView.const view = useMemo( () => createNativeViewHost({ McpAppIframe, onUiAction: (request) => relay.current ? relay.current(request) : Promise.reject(new Error("no thread yet")), }), []);
// then: <NativeTranscript … resolvedMounts={transcript.resolvedMounts} components={{ view }} />Without the reader, a card that arrives as a locator shows as expired.
Theming
Section titled “Theming”Same token schema as the web — Theming — projected to RN style values via resolveNativeTheme instead of CSS variables. NativeTranscript accepts the same theme/mode props; no stylesheet import exists or is needed on native.
Web and native together
Section titled “Web and native together”Because the view-model and hooks are shared, a product with both a web and an RN surface writes its transcript logic once: same policy, same strings, same overrides model — components={{ tool: … }} on web takes a DOM component, on native an RN one, and everything upstream of the renderer is identical.