Getting Started

Let a model build a screen of your app. It calls tools to add nodes and set their props, and GenerativeUIView renders the result in React Native.

Experimental

JSON UI is in alpha, so its API may change.

It’s designed for small on-device models, around 3B parameters: each tool call is a small step they can get right. With large cloud models, json-render may suit you better; Prior Art compares the two.

The package has three parts:

• Tools that let the model read and change the UI, and a system prompt that explains them
• GenerativeUIView, which renders the UI
• Registries of the node types and styles both of them use

Requirements

• A model that supports tool calling, used with the AI SDK’s generateText or streamText

Installation

npm

npm install @react-native-ai/json-ui

yarn

yarn add @react-native-ai/json-ui

pnpm

pnpm add @react-native-ai/json-ui

bun

bun add @react-native-ai/json-ui

Quick Start

import { streamText } from 'ai'
import {
  buildGenUISystemPrompt,
  createGenUITools,
} from '@react-native-ai/json-ui'

const tools = createGenUITools({
  contextId: chatId,
  getSpec: (id) => getSpecForChat(id),
  updateSpec: (id, nextSpec) => setSpecForChat(id, nextSpec),
  toolWrapper: (toolName, execute) => async (args) => {
    console.log('Executing tool', toolName, args)
    return execute(args)
  },
})

const result = streamText({
  model,
  messages,
  tools,
  system: buildGenUISystemPrompt({
    additionalInstructions:
      'Your name is John. Keep responses short. Ask follow-up questions when UI intent is unclear.',
  }),
})

Finally, render the spec set by updateSpec in your app with GenerativeUIView (see Generative UI View):

<GenerativeUIView spec={getChatUISpecFromChats(chatId)} />

For a full usage example, see this file.

Registries

The package exports these registry constants (used by tools and the default renderer):

• GEN_UI_NODE_NAMES — canonical node type names (Text, Paragraph, Label, Heading, Button, TextInput)
• GEN_UI_NODE_HINTS — short descriptions for each node type (for prompts)
• GEN_UI_NODE_NAMES_THAT_SUPPORT_CHILDREN — node types that can have children
• GEN_UI_STYLES — zod schemas for style props (flex, padding, gap, backgroundColor, color, etc.)
• GEN_UI_STYLE_HINTS — metadata for style keys (for prompt text)