Adaptive Cards: an extensive introduction (with practical mental models)

Adaptive Cards are a platform-agnostic UI snippet format authored in JSON that a host app (for example, Microsoft Teams, Bot Framework channels, Copilot experiences, or your own app) can render into native UI that automatically adapts to the host’s look-and-feel. The key idea is: you author one JSON “card,” and each host renders it in a way that fits its container (theme, spacing, fonts, accessibility, etc.). (Microsoft Learn)

This makes Adaptive Cards a “shared language” for lightweight UX inside conversational and workflow-driven apps—especially where you don’t want (or can’t) ship a full custom UI.

1) The core mental model: “Schema + Host = UI”

Think of any Adaptive Card as two things:

1. Schema-driven JSON (your card):
   • You describe what the UI should contain (text blocks, images, columns, input fields, actions).
2. Host rendering rules (the environment):
   • The host decides how it looks and behaves (fonts, spacing, action placement, what features are supported).

That’s why a card that looks perfect in one host may render slightly differently in another. This is not a bug—it’s the purpose: it “adapts.” (Microsoft Learn)

2) Why Adaptive Cards exist (and where they shine)

Adaptive Cards are ideal when you want:

• Consistent UX across multiple surfaces without building custom UI per surface
• Interactive messages (approve/reject, fill a short form, confirm data, pick a date)
• Workflow-driven interactions embedded in chat, notifications, or activity feeds
• Fast iteration: edit JSON instead of redeploying a front-end app

They’re a strong fit in bots and conversational interfaces, where you want “mini-app” interactions directly inside the conversation. (Microsoft Learn)

3) Card anatomy: what a card is made of

At a high level, a card has:

• Body elements (visual + layout)
  • Text, images, containers, columns, fact sets, rich text, etc.
• Inputs (interactive fields)
  • Text inputs, choice sets, toggles, date/time pickers (depends on host support)
• Actions (buttons)
  • Open a link, submit a payload, show a nested card, toggle visibility

Actions are the “interaction gateway” that turns a static card into a workflow UI. The standard action types include:

• Action.OpenUrl (open a link)
• Action.Submit (send a payload back to your bot/service)
• Action.ShowCard (display a sub-card)
• Action.ToggleVisibility (show/hide elements) (Microsoft Learn)

4) Links in Adaptive Cards: what you can (and should) do

There are two primary link patterns you’ll use:

A) “Inline links” inside text

You can embed links in text (host support varies, and some hosts sanitize aggressively). This is great for “learn more,” reference docs, or deep links.

Good for: documentation links, “View item,” “Open ticket,” “Go to dashboard.”

B) Buttons with Action.OpenUrl

This is the most reliable and explicit method across hosts:

• A clear call-to-action button
• Minimal ambiguity
• Works well in mobile and desktop

This maps directly to Action.OpenUrl where you provide the url. (Microsoft Learn)

Best practice: for important navigation, prefer Action.OpenUrl over inline links.

5) Interactivity beyond links: submit, execute, and workflows

When you want the card to send data back (like approvals, form entries, or status changes), you typically use Action.Submit (classic) or newer “universal actions” patterns depending on the host platform.

• Action.Submit sends a payload back to the source application, which is often a bot or service endpoint that you control. (Microsoft Learn)
• In Microsoft Teams, there are platform-specific behaviors and constraints around card actions, especially when cards are used in different capabilities (bots, message extensions, etc.). (Microsoft Learn)

If you’re building for Teams, always validate the supported schema/features because Teams support can be capped to certain versions/features depending on the scenario. (Microsoft Learn)

6) Host differences: “supported features” are not identical everywhere

A recurring real-world issue: not every host supports every schema feature.

Examples of what can differ:

• Schema version supported (some hosts lag behind)
• Which inputs are allowed
• How actions are displayed (primary vs overflow menu)
• Whether certain action types are blocked or replaced by safer alternatives

For Microsoft Teams specifically, Microsoft documents feature support and constraints, including supported Adaptive Card versions in different Teams capabilities. (Microsoft Learn)

For Copilot Studio scenarios, schema support is also explicitly described, including which schema versions are supported in that environment. (Microsoft Learn)

Practical rule: author to the lowest common denominator of your target hosts, and test in each host early.

7) Design principles that keep cards “good” at scale

If you want cards that remain maintainable and user-friendly:

1. Keep it short
   • Cards are “glance + act,” not full pages.
2. One primary action
   • Don’t overload users with 6 buttons.
3. Progressive disclosure
   • Use Action.ShowCard or separate messages for details.
4. Predictable link labels
   • Use verbs: “Open request”, “View report”, “See details”.
5. Be strict with payloads
   • Never trust client-submitted values blindly—treat submissions as untrusted input.

Teams-specific guidance exists on designing effective cards that work well in conversational contexts. (Microsoft Learn)

8) Where Adaptive Cards fit in Microsoft 365 architecture

Typical integration patterns you’ll see:

• Bot Framework bot posts cards → user submits → bot processes → updates state (Microsoft Learn)
• Teams apps (bots/message extensions) use cards to collect input and trigger actions (Microsoft Learn)
• Copilot Studio uses cards to validate info, ask questions, and render API data in structured UI (Microsoft Learn)
• SharePoint/Viva Connections experiences can use card-like patterns (e.g., Adaptive Card Extensions) depending on the scenario (Microsoft Learn)

9) A tiny, practical example: a card with a link button

Below is a minimal JSON idea (conceptually) you’ll commonly use: a title + description + button that opens a URL (ticket, SharePoint item, report, etc.). The important part is the Action.OpenUrl behavior. (Microsoft Learn)

(If you want, in the next message I can provide multiple ready-to-copy templates: “View item”, “Approve/Reject”, “Form submit”, “Status update”, each tuned for Teams/Bot Framework.)

MS Learn links (starting points)

• Adaptive Cards (home/overview): (Microsoft Learn)
• Adaptive Cards for Bot Developers: (Microsoft Learn)
• Actions in Adaptive Cards (OpenUrl/Submit/ShowCard/ToggleVisibility): (Microsoft Learn)
• Teams: Card actions (Teams-specific behavior/constraints): (Microsoft Learn)
• Teams: Cards reference + Adaptive Card support notes: (Microsoft Learn)
• Teams: Design effective cards: (Microsoft Learn)
• Copilot Studio: Adaptive Cards overview and schema support notes: (Microsoft Learn)
• SPFx/Viva: Bot-powered Adaptive Card Extension tutorial: (Microsoft Learn)

Summary table