Adaptive Card Designer

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-adaptive-card-designer

npx shadcn@latest add button dropdown-menu input label select switch textarea tooltip

pnpm add @dnd-kit/core @monaco-editor/react

The designer renders its canvas with the AdaptiveCard renderer, which is installed automatically as a registry dependency.

Overview

AdaptiveCardDesigner is a full visual authoring surface for Adaptive Cards payloads. Where AdaptiveCard only renders a payload, the designer lets users build one — dragging elements from a toolbox, reordering and reparenting them in a structure tree, editing element properties in a side panel, and watching the result render live. The raw payload and the templating sample-data are both editable as JSON at the bottom, and the two views stay in sync.

Typical use cases:

• Internal card authoring — a no-code surface for ops / support teams to compose Teams-style cards and agent UI without hand-writing JSON.
• Template tooling — author the payload that an LLM agent or automation later fills with ${...} bindings, previewed against sample data.
• Embedded editors — drop the designer into an automation-node config or a CMS, read the emitted payload back via onChange.

The designer works on its own normalized node tree internally (stable per-node ids, uniform child slots) and serializes back to a standard AdaptiveCardPayload on every edit.

Layout

The designer is a three-pane layout with a toolbar above and paired JSON editors below:

Usage

Uncontrolled

import { AdaptiveCardDesigner } from '@docyrus/ui/components/adaptive-card-designer';
import { type AdaptiveCardPayload } from '@docyrus/ui/components/adaptive-card';

const starter: AdaptiveCardPayload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [{ type: 'TextBlock', text: 'Hello, **Adaptive Cards**!', weight: 'bolder' }]
};

<AdaptiveCardDesigner
  defaultPayload={starter}
  defaultSampleData={{ user: { name: 'Alice' } }}
  onChange={({ payload, sampleData }) => console.log(payload, sampleData)} />

Controlled

Pass payload / sampleData to drive the designer from outside. onChange fires after every edit:

const [payload, setPayload] = useState<AdaptiveCardPayload>(starter);
const [data, setData] = useState<unknown>({});

<AdaptiveCardDesigner
  payload={payload}
  sampleData={data}
  onChange={next => { setPayload(next.payload); setData(next.sampleData); }} />

Read-only inspection

readOnly disables every mutation — toolbox drag, drop zones, property edits, JSON edits, undo / redo / new, and keyboard shortcuts. Theme / width / preview / copy stay active, and selection remains enabled so users can click through the tree and inspect properties:

<AdaptiveCardDesigner payload={payload} readOnly />

Custom toolbox items

Append your own draggable types alongside the built-ins. Each item supplies a factory that returns a fresh node on every drop:

import { Sparkles } from 'lucide-react';
import { type ToolboxItem } from '@docyrus/ui/components/adaptive-card-designer';

const extras: ToolboxItem[] = [
  {
    id: 'Docyrus.UserChip',
    type: 'Docyrus.UserChip',
    label: 'User Chip',
    icon: Sparkles,
    group: 'advanced',
    keywords: ['user', 'chip', 'avatar'],
    factory: () => ({
      __designerId: crypto.randomUUID(),
      type: 'Docyrus.UserChip',
      props: { userId: '' },
      slots: {}
    })
  }
];

<AdaptiveCardDesigner
  extraToolboxItems={extras}
  customElements={{ 'Docyrus.UserChip': ({ element }) => <UserChip id={element.userId} /> }} />

Pair extraToolboxItems (authoring) with customElements (rendering) so the canvas knows how to draw the type you just added. customElements and hostConfig are forwarded straight to the inner <AdaptiveCard>.

Trimming the toolbar

<AdaptiveCardDesigner hideToolbarButtons={['new', 'copy']} />

API Reference

AdaptiveCardDesignerProps

EditorAgent integration

Pair useApplyAdaptiveCard with renderAiAssistant to let an LLM author Adaptive Card payloads. The hook owns the designer's controlled payload + sampleData and exposes an applyAdaptiveCard tool that the agent calls to commit a new payload. The tool rejects primitives / arrays / null and requires type: "AdaptiveCard" at the root so a malformed call cannot crash the designer.

import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { AdaptiveCardDesigner, useApplyAdaptiveCard } from '@docyrus/ui/components/adaptive-card-designer';

export function AdaptiveCardPlayground({ client, user, agentId }) {
  const adaptiveCard = useApplyAdaptiveCard();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <AdaptiveCardDesigner
      payload={adaptiveCard.payload ?? undefined}
      sampleData={adaptiveCard.sampleData}
      onChange={(next) => {
        adaptiveCard.setPayload(next.payload);
        adaptiveCard.setSampleData(next.sampleData);
      }}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        <EditorAgent
          agentId={agentId}
          client={client}
          user={user}
          open={open}
          onClose={onClose}
          clientTools={adaptiveCard.tools}
        />
      )}
    />
  );
}

The matching backend agent must register a tool named applyAdaptiveCard whose input schema mirrors { payload: object (required), sampleData?: any, explanation?: string }.

Composition

The default AdaptiveCardDesigner is a single component that composes a provider + the panes. For custom layouts you can assemble the pieces yourself:

Helpers

The component also exports its tree model utilities for advanced integrations (custom serializers, programmatic edits, validation):

Type Exports

Related

• AdaptiveCard — the renderer the designer canvas is built on.
• useAdaptiveCard — the hook behind the renderer.