CopilotKit

GenerativeUISurface

A named place in a React Native app where the agent can render UI, with a description the agent reads in each run that starts while it is mounted.

Open your coding agent in your project's folder, or in an empty folder for a new app.This runs in a coding agent on your computer.

Overview

GenerativeUISurface marks a place in your app as a target for generated UI. The targets are sent when a run starts, so the agent sees its id and description in each run that starts while it is mounted, and can render a surface into it. Until then it shows fallback.

A target follows the thread that is active in the provider: the thread of the last run that started on the core, of any agent, also one that the provider's agentIds leaves out. To show the output of one particular agent, for example a background run on a home screen, render that agent's activity message with GenerativeUIActivity instead.

Render it under GenerativeUIProvider: outside one it throws, naming GenerativeUIProvider, unlike GenerativeUIActivity, which renders nothing. Under a provider that has no ui, it shows its fallback and warns in development. The concepts are the same as on the web; see Surfaces.

The operations of its surface that were rejected, by the runtime or by the app, reach its Wrapper (see below); by default it shows "Part of this UI couldn't be shown." under the surface. The ones that the runtime rejected never reach errorBoundary.onError; the ones that the app rejected go there too, as usual.

Import

import { GenerativeUISurface } from "@copilotkit/react-native/generative-ui";

Props

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Prop

Type

Usage

import { useRef } from "react";
import { ScrollView, View } from "react-native";
import { GenerativeUISurface } from "@copilotkit/react-native/generative-ui";
import { bankUI } from "./bankUI";

export function AccountsScreen() {
  const scrollRef = useRef<ScrollView>(null);
  const insightsY = useRef<number | undefined>(undefined);
  // A target that mounts while the agent renders into it gets the call before
  // its first layout, and content above it can move as the generation starts.
  // Until this time, a new position of the target scrolls to it again.
  const followUntil = useRef(0);

  const scrollToInsights = () => {
    followUntil.current = Date.now() + 1000;
    // Undefined before the first layout: onLayout scrolls then.
    if (insightsY.current !== undefined) {
      scrollRef.current?.scrollTo({ y: insightsY.current, animated: true });
    }
  };

  return (
    <ScrollView ref={scrollRef}>
      <Balances />
      {/* A direct child of the ScrollView, so its layout y is its offset in the content. */}
      <View
        onLayout={(event) => {
          const { y } = event.nativeEvent.layout;
          if (y === insightsY.current) return; // same position: nothing to correct
          insightsY.current = y;
          if (Date.now() < followUntil.current) {
            scrollRef.current?.scrollTo({ y, animated: true });
          }
        }}
      >
        <GenerativeUISurface
          id="insights"
          ui={bankUI}
          description="Under the balances. Show spending insights here."
          components={["InsightCard"]}
          fallback={<InsightsPlaceholder />}
          onGenerationStart={scrollToInsights}
        />
      </View>
    </ScrollView>
  );
}

Related

  • GenerativeUIActivity: render one agent's surface from its activity message
  • Surfaces: descriptions, component limits and one target per item