# 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.

## Overview [#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`](/reference/react-native/components/GenerativeUIActivity) instead.

Render it under [`GenerativeUIProvider`](/reference/react-native/components/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](/generative-ui/components/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]

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

## Props [#props]

<PropertyReference name="id" type="string" required>
  The target id. The agent names it when it renders here.
</PropertyReference>

<PropertyReference name="description" type="string">
  What the area is and what belongs in it, for example "The home screen,
  under the greeting." The agent reads it in each run that starts while the
  target is mounted, so write it like an instruction.
</PropertyReference>

<PropertyReference name="ui" type="GenerativeUI">
  The catalog of the provider. It types the names in `components`. Passing a
  different catalog logs a warning in development; the components are always
  checked against the provider's catalog.
</PropertyReference>

<PropertyReference name="components" type="readonly GenerativeUIComponentName<UI>[]">
  The only components the agent can use in this target, the root included.
  Needs `ui`. Left out, every component of the catalog is allowed. Names that
  are not in the provider's catalog are dropped (with a warning in
  development), repeats are dropped, and of the names that remain only the
  first 100 are used. An empty list, or a
  list with only unknown names, allows no component at all: the target stays
  mounted and the agent sees it, but every operation that places a component
  in it is rejected.
</PropertyReference>

<PropertyReference name="fallback" type="ReactNode" default="null">
  Shown until a surface targets this id, and while the provider has no `ui`.
  After the agent deletes the surface, the target shows the newest surface of
  the same target and thread that is not deleted, if there is one, and the
  fallback otherwise.
</PropertyReference>

<PropertyReference name="style" type="StyleProp<ViewStyle>">
  Style of the `View` around the surface, which has the test ID
  `generative-ui-surface-<id>`. It applies while the fallback shows, too.
</PropertyReference>

<PropertyReference name="onGenerationStart" type="() => void">
  Called once each time the agent starts to render into this target: for
  each `render_ui` call, on a new surface or as an update, also when React
  batches several starts into one render. Also called when the target
  mounts, its `id` changes, or the active thread changes, while the agent is
  rendering into it. It is not called again for the same start when the
  component renders again, mounts under `<React.StrictMode>`, or gets a new
  callback. It runs after React commits the render; an error it throws is
  caught and logged with `console.error`, and the surface stays. React
  Native has no `autoScroll`: use this to scroll the target into view.

  A call counts as a new start when the surface goes to streaming from
  another status, or stays streaming while its rejected operations are reset
  (the runtime resets them at the start of each call). When the app never
  sees the end of one call, for example because a reconnect delivers the
  next call already streaming and neither call had a rejected operation, the
  two calls count as one start.
</PropertyReference>

<PropertyReference name="Wrapper" type="ComponentType<GenerativeUIActivityWrapperProps>">
  Replaces the default wrapper around the surface. It gets the same props as
  the [`Wrapper` of `GenerativeUIActivity`](/reference/react-native/components/GenerativeUIActivity):
  `surfaceId`, `isStreaming`, `rejected` (the operations of the latest
  `render_ui` call that the runtime or the app rejected), `error` (set when
  `rejected` is not empty) and `children`. The default draws no view of its
  own, so the surface lays out in the view around it (`style`), and shows
  "Part of this UI couldn't be shown." under the surface when operations
  were rejected. The fallback is not wrapped. A surface whose
  `createSurface` was rejected never exists, so the target keeps showing its
  fallback and no `Wrapper` renders. When the app rejected it,
  `errorBoundary.onError` gets it, and `GenerativeUIActivity` with `target`
  set to this id shows it from the activity message. When the runtime
  rejected it, there is no activity message: only the model learns of it, in
  the result of its `render_ui` call, and nothing on the device shows it.
  The one exception is a `createSurface` with the id of a live surface: the
  runtime adds that rejection to the live surface, whose `Wrapper` shows it.
</PropertyReference>

## Usage [#usage]

```tsx
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 [#related]

- [`GenerativeUIActivity`](/reference/react-native/components/GenerativeUIActivity): render one agent's surface from its activity message
- [Surfaces](/generative-ui/components/surfaces): descriptions, component limits and one target per item
