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 agent-spec yet

The code on this page comes from the showcase's declarative-json-render demo, and agent-spec doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).

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 will render it through your React component registry.

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 for the same scenario with @hashbrownai/react.

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:

    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:

    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.

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

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.

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

JSON Render and Hashbrown solve the same problem with two different rendering libraries. The agent contract is similar. The React glue, validation strategy, and rendering behavior differ.

How is this guide?