# JSON Render

> Bring your own component library. Have the agent emit a JSON spec and render allowed component types through a typed React registry.

> **Not available for a2a yet.** The code on this page comes from the showcase's `declarative-json-render` demo, and a2a doesn't have it yet. See this page for [CopilotKit's Built-in Agent](/generative-ui/json-render), [LangGraph (Python)](/langgraph-python/generative-ui/json-render), [LangGraph (TypeScript)](/langgraph-typescript/generative-ui/json-render).

You have a chat surface and you want the agent to draw a dashboard from a typed JSON spec. By the end of this guide, the agent will emit a `{ root, elements }` object, and [`@json-render/react`](https://www.npmjs.com/package/@json-render/react) will render it through your React component registry.

## When to use this [#when-to-use-this]

- **Structured UI with a typed contract** where the renderer accepts known component types.
- **Tolerance for prose preamble + code fences** in the agent's output (the demo's parser handles them).
- **Cases where you already use json-render** elsewhere or prefer a Zod-described catalog.

If you'd rather have a streaming progressive render than a one-shot JSON render, see the sibling page [Hashbrown](/a2a/generative-ui/hashbrown) for the same scenario with `@hashbrownai/react`.

## Frontend [#frontend]

The demos use `@json-render/react` and `@json-render/core` 0.18.0, with Zod 4 for the catalog. Demos that also use Zod 3 import Zod 4 through the `zod4` package alias.

1. Copy `catalog.ts` and `registry.tsx`. `catalog.ts` defines component names and Zod prop schemas with `defineCatalog`. `registry.tsx` uses `defineRegistry(catalog, ...)` to bind those names to React components.
2. Copy `json-render-renderer.tsx`. It parses the assistant content and falls back to the normal assistant message until it can parse a spec:

   ```tsx title="json-render-renderer.tsx (excerpt)"
   export function JsonRenderAssistantMessage(
     props: CopilotChatAssistantMessageProps,
   ) {
     const content =
       typeof props.message.content === "string" ? props.message.content : "";
     const spec = useMemo(() => parseSpec(content), [content]);

     if (!spec) return <CopilotChatAssistantMessage {...props} />;

     return (
       <JSONUIProvider registry={registry}>
         <Renderer
           spec={spec as unknown as Parameters<typeof Renderer>[0]["spec"]}
           registry={registry}
         />
       </JSONUIProvider>
     );
   }
   ```

3. Install the renderer in the `assistantMessage` slot of `CopilotChat`:

   ```tsx title="chat.tsx"
   <CopilotChat
     messageView={{
       assistantMessage:
         JsonRenderAssistantMessage as unknown as typeof CopilotChatAssistantMessage,
     }}
   />
   ```

4. Tell the agent to answer with one `{ root, elements }` object, as shown in [Backend](#backend).

The demo's `parseSpec` allowlists component types and checks the basic object shape, but does **not** validate emitted props against the Zod schemas at runtime. Validate props before rendering if you rely on that guarantee.

## Backend [#backend]

The agent emits a `{ root, elements }` JSON object as the assistant message content. `root` references a top-level element id; `elements` maps each id to a `{ type, props, children }` triple matching the catalog.

```json title="example agent output"
{
  "root": "revenue-card",
  "elements": {
    "revenue-card": {
      "type": "MetricCard",
      "props": { "label": "Total revenue", "value": "$184,302", "trend": "+12%" },
      "children": ["by-region"]
    },
    "by-region": {
      "type": "BarChart",
      "props": {
        "title": "Revenue by region",
        "description": null,
        "data": [
          { "label": "North America", "value": 112000 },
          { "label": "EMEA", "value": 72302 }
        ]
      }
    }
  }
}
```

The example uses a `MetricCard` root and its registered `BarChart` child. The renderer tolerates a prose preamble or code fence around the JSON, but the agent prompts ask for plain JSON.

## Comparing the two patterns [#comparing-the-two-patterns]

JSON Render and [Hashbrown](/a2a/generative-ui/hashbrown) solve the same problem with two different rendering libraries. The agent contract is similar. The React glue, validation strategy, and rendering behavior differ.

<IntegrationGrid path="generative-ui/json-render" />
