Adaptive Card

AdaptiveCard renders an Adaptive Cards JSON document with native React Native primitives — no WebView. It is a 1:1 native port of the web @docyrus/ui Adaptive Card renderer and supports the same payloads produced by the Docyrus Adaptive Card Designer: every element, input, action, the chart family (including Teams' grouped and stacked bars), templating (${...}, $data, $when), requires/fallback, and host-config overrides.

Installation

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

pnpm add react-native-svg @react-native-community/datetimepicker (optional)

react-native-svg powers the chart family, the progress ring, and CDN icons. @react-native-community/datetimepicker is optional — when absent, Input.Date / Input.Time fall back to a plain text field.

Usage

import { AdaptiveCard } from '@/components/docyrus-native/adaptive-card';

const payload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    { type: 'TextBlock', text: 'Hello **world**', size: 'large', weight: 'bolder', wrap: true },
    { type: 'Input.Text', id: 'name', label: 'Name', isRequired: true },
  ],
  actions: [{ type: 'Action.Submit', title: 'Send', style: 'positive' }],
};

<AdaptiveCard
  payload={payload}
  onAction={(event) => {
    if (event.type === 'submit') console.log(event.data); // { name: '...' }
  }}
/>

With templating

Pass a data context to expand ${...} expressions, $data scoping/repeats, and $when conditions before rendering.

<AdaptiveCard
  payload={{
    type: 'AdaptiveCard',
    version: '1.5',
    body: [
      { type: 'TextBlock', text: '${greeting}, ${name}!', weight: 'bolder' },
      { type: 'TextBlock', $data: '${items}', text: '${title} — ${price}' },
    ],
  }}
  data={{ greeting: 'Hello', name: 'Erhan', items: [{ title: 'Coffee', price: '$3.50' }] }}
/>

Handling submit / execute

onAction fires for every action the user triggers, so you can persist forms, route Teams Action.Execute verbs, or log analytics. Submit/execute events arrive only after input validation passes.

<AdaptiveCard
  payload={formPayload}
  onAction={async (event) => {
    if (event.type === 'submit') {
      await client.post('/forms', event.data); // { name: '...', topic: '...' }
    } else if (event.type === 'execute') {
      await invokeAgent(event.verb, event.data); // event.verb identifies the action
    }
  }}
/>

Host config override

Adaptive Cards' abstract enums (good, attention, medium, vertical actions…) resolve through a host config. defaultHostConfig reads the app's theme tokens, so light/dark is automatic. Pass hostConfig to deep-merge overrides:

<AdaptiveCard
  payload={payload}
  hostConfig={{ actions: { maxActions: 3, actionsOrientation: 'vertical' } }}
/>

Custom / overridden element types

customElements registers a renderer for any type string and takes precedence over the built-ins — use it for host-specific elements or to swap a placeholder (e.g. a real Media player) for a native one:

import { Text } from 'react-native';

<AdaptiveCard
  payload={payload}
  customElements={{
    'Docyrus.UserChip': ({ element }) => <UserChip id={element.userId} />,
    Media: ({ element }) => <VideoPlayer source={element.sources?.[0]?.url} />,
  }}
/>

Teams cards (PascalCase enums)

Microsoft's schema spells enum values in PascalCase ("Large", "Bolder", "Good", "PartToWhole"), and Teams matches them case-insensitively. The native renderer matches the same way, through matchesEnum and lookupEnum from lib/enum-match. So a card copied from Microsoft's documentation renders the same as its camelCase equivalent. This covers text size, weight and font type, colours, alignment, spacing, container, table and badge styles, image size and style, action style and mode, chart colour sets, display mode, thickness and value format. An unrecognized value falls back to the default instead of dropping the styling.

<AdaptiveCard
  payload={{
    type: 'AdaptiveCard',
    version: '1.5',
    body: [
      { type: 'TextBlock', text: 'Deployment finished', size: 'Large', weight: 'Bolder', color: 'Good' },
      { type: 'Container', style: 'Emphasis', items: [{ type: 'TextBlock', text: 'All checks passed', horizontalAlignment: 'Center' }] }
    ],
    actions: [{ type: 'Action.Submit', title: 'Acknowledge', style: 'Positive' }]
  }}
/>

Charts (Teams contract)

Microsoft's chart shapes differ per chart type, and the renderer accepts every spelling:

• Bar charts take { x, y } points.
• Pie and donut take { legend, value }.
• Gauge segments size themselves with size (or value).
• Chart.Line and Chart.VerticalBar.Grouped take one entry per series, { legend, values: [{ x, y }] }.
• Chart.HorizontalBar.Stacked nests the segments under a titled bar: { title, data: [{ legend, value, color? }] }.

const charts = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    {
      type: 'Chart.VerticalBar.Grouped',
      title: 'Revenue by region',
      stacked: false,        // true stacks the series on one bar
      showBarValues: true,
      xAxisTitle: 'Quarter',
      yAxisTitle: 'Revenue',
      valueFormat: 'short',
      data: [
        { legend: 'EMEA', values: [{ x: 'Q1', y: 1200 }, { x: 'Q2', y: 1800 }] },
        { legend: 'APAC', values: [{ x: 'Q1', y: 900 }, { x: 'Q2', y: 1400 }] }
      ]
    },
    {
      type: 'Chart.HorizontalBar.Stacked',
      title: 'Tickets by team',
      colorSet: 'diverging',
      data: [
        { title: 'Support', data: [{ legend: 'Open', value: 12 }, { legend: 'Closed', value: 30 }] },
        { title: 'Sales', data: [{ legend: 'Open', value: 5 }, { legend: 'Closed', value: 18 }] }
      ]
    },
    {
      type: 'Chart.HorizontalBar',
      displayMode: 'PartToWhole', // scale each bar against the total; hides the value axis
      data: [{ x: 'Won', y: 42 }, { x: 'Lost', y: 18 }]
    }
  ]
};

Headless hook flow

For a custom toolbar, programmatic validation, or a non-default layout, drive the renderer with useAdaptiveCard + AdaptiveCardView. A failed submit focuses the first invalid Input.Text / Input.Number:

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

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

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

Filtered Input.ChoiceSet (Data.Query)

A style: 'filtered' ChoiceSet that declares choices.data calls onChoiceQuery with the dataset + debounced search text; return the matching choices:

<AdaptiveCard
  payload={payload}
  onChoiceQuery={async ({ dataset, search }) => {
    const rows = await client.get(`/lookup/${dataset}?q=${search}`);
    return rows.map(r => ({ title: r.label, value: r.id }));
  }}
/>

API Reference

Supported elements

Supported actions

selectAction is supported on Container, Column, ColumnSet, Image, Icon, TableCell, CompoundButton, and the card root.

Action dispatch

Every action emits a typed event through onAction (AdaptiveCardActionEvent, a discriminated union on type):

data follows the spec's associatedInputs contract: 'auto' (default) collects every visible input in scope; 'none' ships only action.data. ${input.<id>} placeholders inside action.data are substituted with the current input values.

Helpers

All exported from @/components/docyrus-native/adaptive-card:

Native notes

• Charts render with react-native-svg, without the tooltips of the web charting library. Plain vertical and horizontal bars and the stacked horizontal bar are View-based; the grouped vertical bar, pie, donut, line and gauge are SVG. Horizontal bars show a 0 / ½ / max value axis unless displayMode is AbsoluteNoAxis or PartToWhole, and the grouped chart draws a y-axis with gridlines.
• Table gives a column with a numeric width a fixed size (width × 50 px, same as web) and scrolls horizontally when the columns are wider than the card.
• Text sizes never go below text-xs (12 px): badge extraSmall / small, citations, chart labels and compound-button badges were normalized, matching web.
• Media has no bundled player: it shows the poster (or an audio chip) and opens the source via Linking on tap. Component / LoopComponent render lossless placeholders. Register a customElements override for inline playback.
• TextBlock / FactSet markdown supports the inline subset: bold, italic, strikethrough, inline code, links. Block lists are not formatted.
• Icons (Icon, Badge.icon, accordion/tab headers) map Fluent names to Font Awesome glyphs loaded from the Docyrus icon CDN.

Type Exports

Every other schema type from adaptive-card-types.ts is re-exported from the barrel as well. That includes the enums (AdaptiveCardSpacing, …Color, …FontSize, …FontWeight, …FontType, alignments, …ContainerStyle, …ImageSize / …ImageStyle, …ActionStyle / …ActionMode, …), the elements (AdaptiveCardTextBlock, …RichTextBlock, …TextRun, …Image, …Media, …Container, …ColumnSet, …Table*, …Badge, …Carousel*, …Accordion*, …TabSet, …), the inputs (AdaptiveCardInputText, …InputNumber, …InputDate, …InputTime, …InputToggle, …InputChoiceSet, …InputRating, AdaptiveCardChoice), the actions (AdaptiveCardActionSubmit, …Execute, …OpenUrl, …ShowCard, …ToggleVisibility, …ResetInputs), the events (AdaptiveCardSubmitEvent, …) and the host-config parts, so the native barrel matches the web one.

Related

• useAdaptiveCard: the headless hook that powers the component.
• useDocyrusAdaptiveCardItemDetail / useDocyrusAdaptiveCardItemList: generate cards from a Docyrus field list plus records.
• registerElement(type, renderer) — register a global custom element renderer.
• expandTemplate(payload, data) / evaluateExpression(expr, scope) — standalone templating helpers.