Overview

ToonUI is a structured UI protocol for AI chat products.

It lets a model return normal markdown plus compact toon-ui blocks, while your app keeps ownership of rendering, tools, auth, persistence, and business logic.

Recommended path

Most teams should start with:

Server: @toon-ui/core
Client: @toon-ui/react
AI loop: Vercel AI SDK

Vercel AI SDK is the recommended documentation path because it is common, well-supported, and ergonomic for React/Next.js chat products.

It is not a hard requirement. If you use another SDK, keep the same ToonUI architecture and replace only the model/message loop.

The two packages

There is intentionally no umbrella package. Do not import React code on the server just to get protocol helpers.

The core idea

The model can only emit the standard ToonUI components your app configures.

import { createToonProtocol } from '@toon-ui/core';

const toon = createToonProtocol({
  components: ['text', 'card', 'form', 'field', 'button', 'table'],
});

That active catalog drives:

• toon.prompt
• toon.rules
• toon.catalog
• validation against generated output

On the client, register matching React components:

'use client';

import { createToonReactRuntime } from '@toon-ui/react';

const toon = createToonReactRuntime({
  components: {
    text: TextComponent,
    card: CardComponent,
    form: FormComponent,
    field: FieldComponent,
    button: ButtonComponent,
    table: TableComponent,
  },
});

If the AI emits a component outside the active catalog, ToonUI rejects it instead of silently rendering unsupported UI.

Data capture rules

ToonUI is a DSL, so structure is part of the contract:

• field nodes collect structured values only inside a form.
• If a dialog, sheet, popover, or card needs input, nest a form inside that container.
• Use description="..." for short guidance on supported containers such as card, form, alert, confirm, dialog, item, empty, and chart.
• Use value="..." to prefill a field. Do not represent input values as nested text.

dialog "Contact customer" trigger="Open contact form" description="Send a message to the customer.":
  form "Customer message" description="Write the message the customer will receive.":
    field message textarea "Message" placeholder="Type your message..." required
    button primary "Send message" submit

What ToonUI is not

ToonUI is not:

• an agent framework
• a tool executor
• a backend workflow engine
• a v0-style frontend generator
• an alternative to JSON renderers like json-render.dev
• runtime React generation for production
• a replacement for your design system

The model describes semantic UI. Your app decides what behavior happens next.

Learning path

Read in this order:

1. Start Here
2. Installation
3. Quickstart
4. Configuration
5. Vercel AI SDK guide
6. Core package
7. React package

Next step

Go to Start Here.