json-render/apps/web/app/(main)/docs/page.mdx

export const metadata = { title: "Introduction" }

# Introduction

json-render is a framework for **Generative UI** — AI-generated interfaces that are safe, predictable, and render natively on any platform.

## What is Generative UI?

Most AI integrations treat the interface as fixed. Developers build layouts ahead of time, and AI fills in the data — a chatbot response, a summary, a recommendation. The UI itself never changes.

**Generative UI is different.** The AI generates the interface itself: which components to show, how to arrange them, what data to bind, what actions to wire up. Every response can produce a unique, purpose-built UI tailored to the user's request.

The challenge is that unconstrained AI output is unpredictable. It can hallucinate component names, produce invalid structures, or generate unsafe code. You need a way to let AI be creative with layout and composition while keeping it within boundaries you control.

That is what json-render does. You define a **catalog** of components and actions. AI generates JSON constrained to that catalog. Your components render the result natively — on web or mobile — with full type safety and no arbitrary code execution.

## How json-render Works

### 1. Define your catalog

A catalog declares what AI can use: components with typed props, actions with typed params.

```typescript
import { defineCatalog } from '@json-render/core';
import { schema } from '@json-render/react';
import { z } from 'zod';

export const catalog = defineCatalog(schema, {
  components: {
    Card: {
      props: z.object({ title: z.string() }),
      slots: ["default"],
    },
    Metric: {
      props: z.object({
        label: z.string(),
        value: z.string(),
      }),
    },
  },
});
```

### 2. AI generates a spec

Given a prompt like "show me a revenue dashboard", AI outputs a JSON spec — a flat tree of elements constrained to your catalog:

```json
{
  "root": "card-1",
  "elements": {
    "card-1": {
      "type": "Card",
      "props": { "title": "Revenue Dashboard" },
      "children": ["metric-1", "metric-2"]
    },
    "metric-1": {
      "type": "Metric",
      "props": { "label": "Total Revenue", "value": "$48,200" }
    },
    "metric-2": {
      "type": "Metric",
      "props": { "label": "Growth", "value": "+12%" }
    }
  }
}
```

### 3. Your components render it

Map catalog types to real components with a registry, then render the spec:

```tsx
import { Renderer, StateProvider, VisibilityProvider } from '@json-render/react';

<StateProvider initialState={{}}>
  <VisibilityProvider>
    <Renderer spec={spec} registry={registry} />
  </VisibilityProvider>
</StateProvider>
```

The result is a native UI built from your own components — not an iframe, not markdown, not generated code. The AI chose the structure; you control everything else.

## Key Concepts

- **[Catalog](/docs/catalog)** — Define the components, actions, and validation functions AI can use. This is the contract between your app and the AI.
- **[Registry](/docs/registry)** — Map catalog types to platform-specific implementations. React components on web, React Native views on mobile.
- **[Specs](/docs/specs)** — The JSON output AI generates. A flat tree of typed elements with props, children, data bindings, and visibility conditions.
- **[Streaming](/docs/streaming)** — Render progressively as the AI responds. Each JSONL patch adds to the spec and the UI updates in real time.
- **[Data Binding](/docs/data-binding)** — Bind props to runtime data with `$state` paths, repeat elements over arrays, and wire two-way input bindings.
- **[Visibility](/docs/visibility)** — Show or hide elements based on state conditions. The AI can generate conditional UIs without writing logic.
- **[Generation Modes](/docs/generation-modes)** — Generate standalone UI (playground/builder) or inline UI within a chat conversation.

## Next

- [Installation](/docs/installation) — Add json-render to your project
- [Quick Start](/docs/quick-start) — Build your first generative UI in 5 minutes