Adaptive Card

Installation

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

npx shadcn@latest add avatar button calendar card collapsible dropdown-menu input label popover radio-group select separator switch textarea tooltip

pnpm add react-markdown remark-gfm

Overview

AdaptiveCard consumes Microsoft's Adaptive Cards 1.5 JSON schema and renders it using Docyrus primitives (shadcn). The two primary use cases are:

• Agent-native UI — Adaptive Cards are a JSON structure LLM agents already understand and emit reliably. Use the renderer to surface agent output as actionable UI.
• Microsoft Teams interop — the same payload a Teams Bot returns can render directly inside Docyrus messages, comments, and notifications.

The component is a thin wrapper around useAdaptiveCard. Drop in a payload, get a fully interactive card back. For advanced flows (server-driven validation, custom toolbars), use the hook directly.

Usage

Basic render

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

const payload: AdaptiveCardPayload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    { type: 'TextBlock', text: 'Hello, **Adaptive Cards**!', size: 'large', weight: 'bolder' }
  ],
  actions: [
    { type: 'Action.OpenUrl', title: 'Open docs', url: 'https://adaptivecards.io/' }
  ]
};

<AdaptiveCard payload={payload} onAction={event => console.log(event)} />

Handling submit / execute

<AdaptiveCard
  payload={formPayload}
  onAction={async (event) => {
    if (event.type === 'submit') {
      await fetch('/api/forms', { method: 'POST', body: JSON.stringify(event.data) });
    } else if (event.type === 'execute') {
      // event.verb identifies the bot action
      await invokeBot(event.verb, event.data);
    }
  }} />

onAction fires for every action the user triggers — submit, execute, openUrl, toggleVisibility, showCard — so consumers can log analytics, persist drafts, or route Teams Action.Execute calls.

Host config override

The renderer maps Adaptive Cards' abstract enums (Good, Attention, Bleed, Medium) to concrete colors/spacing/sizes via a host config. defaultHostConfig reads from the repo's CSS-variable tokens, so dark mode is automatic. Pass hostConfig to deep-merge overrides:

<AdaptiveCard
  payload={payload}
  hostConfig={{
    actions: { maxActions: 3, actionsOrientation: 'vertical' },
    colors: { good: { default: '#0a7' } }
  }} />

Custom element types

Register a renderer for an unknown type string via customElements:

<AdaptiveCard
  payload={payload}
  customElements={{
    'Docyrus.UserChip': ({ element }) => <UserChip id={element.userId} />
  }} />

Custom renderers take precedence over the built-in registry. The unknown-type fallback continues to honor the schema's fallback chain otherwise.

Hook-driven flow

For advanced cases (custom toolbar, programmatic submit, server-side validation), consume the hook directly:

import { AdaptiveCardView, useAdaptiveCard } from '@docyrus/ui/components/adaptive-card';

function CustomFlow({ payload }) {
  const adaptive = useAdaptiveCard(payload, { onAction });

  return (
    <>
      <button onClick={() => adaptive.controls.validateAll()}>Pre-validate</button>
      <AdaptiveCardView cardProps={adaptive.cardProps} />
    </>
  );
}

See useAdaptiveCard for the full hook surface.

Schema coverage

The renderer ships complete coverage of the Adaptive Cards 1.5 schema:

Out of scope in v1: live refresh polling, server-side Action.Execute transport (we hand verb + data to onAction), authentication block rendering.

Action dispatch

Every action emits a typed event through onAction:

data follows the spec's associatedInputs contract: 'auto' (default) collects every visible input in the current scope; 'none' ships only action.data. For Action.ShowCard submits, the nested card's inputs merge into the parent's.

API Reference

AdaptiveCardProps

AdaptiveCardViewProps

AdaptiveCardView is the presentational layer that the hook drives. Use it when you call useAdaptiveCard yourself.

Components

Helpers

Type Exports

Security notes

• No raw HTML — markdown in TextBlock / FactSet is rendered with react-markdown + remark-gfm and the default raw-HTML-disabled config. Card payloads that arrive from LLMs or external bots cannot inject <script>.
• Background-image URL allowlist — parseAdaptiveCard rejects javascript: and data:text/html URIs in backgroundImage. Only https:, http:, and data:image/* resolve.
• External links — Action.OpenUrl opens in a new tab with rel="noopener noreferrer".