AdaptiveCards for JavaScript

As we described in Getting Started page, an Adaptive Card is a JSON-serialized card object model. This is a JavaScript library for generating client-side HTML in the browser.

Important

Breaking changes from v0.5

  1. Package renamed from microsoft-adaptivecards to adaptivecards
  2. The static AdaptiveCards.setHostConfig() has been moved to an instance member of AdaptiveCard. E.g., myCard.hostConfig = {}
  3. HostConfig has gone though various renames and moves. See the sample.json Host Config for current structure
  4. There have also been some schema changes from the v0.5 preview, which are outlined here
  5. The static renderCard() function was removed as it was redundant with the class methods. Use adaptiveCard.render() as described below.

Install

Node

npm install adaptivecards --save

CDN

<script src="https://unpkg.com/adaptivecards/dist/adaptivecards.js"></script>

Usage

Import the module

// import the module
import * as AdaptiveCards from "adaptivecards";

// or require it
var AdaptiveCards = require("adaptivecards");

// or use the global variable if loaded from CDN
AdaptiveCards.renderCard(...);

Render a card

// Author a card
// In practice you'll probably get this from a service
// see http://adaptivecards.io/samples/ for inspiration
var card = {
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "Image",
            "url": "http://adaptivecards.io/content/adaptive-card-50.png"
        },
        {
            "type": "TextBlock",
            "text": "Hello **Adaptive Cards!**"
        }
    ],
    "actions": [
        {
            "type": "Action.OpenUrl",
            "title": "Learn more",
            "url": "http://adaptivecards.io"
        },
        {
            "type": "Action.OpenUrl",
            "title": "GitHub",
            "url": "http://github.com/Microsoft/AdaptiveCards"
        }
    ]
};

// Create an AdaptiveCard instance
var adaptiveCard = new AdaptiveCards.AdaptiveCard();

// Set its hostConfig property unless you want to use the default Host Config
// Host Config defines the style and behavior of a card
adaptiveCard.hostConfig = new AdaptiveCards.HostConfig({
    fontFamily: "Segoe UI, Helvetica Nue, sans-serif"
    // More host config options
});

// Set the adaptive card's event handlers. onExecuteAction is invoked
// whenever an action is clicked in the card
adaptiveCard.onExecuteAction = function(action) { alert("Ow!"); }

// For markdown support you need a third-party library
// E.g., to use markdown-it, include in your HTML page:
//     <script type="text/javascript" src="https://unpkg.com/markdown-it/dist/markdown-it.js"></script>
// And add this code to replace the default markdown handler:
//     AdaptiveCards.processMarkdown = function(text) { return markdownit().render(text); }

// Parse the card payload
adaptiveCard.parse(card);

// Render the card to an HTML element:
var renderedCard = adaptiveCard.render();

// And finally insert it somewhere in your page:
document.body.appendChild(renderedCard);

Webpack

If you don't want the library included in your bundle, make sure the script is loaded and add the following the your webpack.config.json

module.exports = {
  ...
  externals: [
    { adaptivecards: { var: "AdaptiveCards" } }
  ]
};

Customization

There are 3 ways to customize the adaptive card rendering:

  1. Host Config
  2. CSS styling
  3. Custom element rendering

HostConfig

A Host Config is a shared configuration object that all renderers understand. This allows you to define common styles (e.g., font family, font sizes, default spacing) and behaviors (e.g., max number of actions) that will be automatically interpreted by each platform renderer.

The goal is that the native UI generated by each platform renderer will look very similar with minimal work on your part.

var renderOptions = {
    ...
    hostConfig: {
        // Define your host config object here
        // See the HostConfig docs for details
    }
};

CSS Styling

Use CSS for fine-grained styling of the card HTML.

The following CSS classes will be added to various elements.

CSS class Usage
.ac-container containers
.ac-selectable elements with selectAction
.ac-image image
.ac-pushButton actions rendered like buttons
.ac-linkButton actions rendered like links
.ac-input input controls
.ac-textInput text input
.ac-multiline multiline text input
.ac-numberInput number input
.ac-dateInput date input
.ac-timeInput time input
.ac-multichoiceInput multichoice input

Custom Element Rendering

For full control of the renderer, you can access the global registry to modify behavior of element rendering, or even introduce your own.

  • For Actions use AdaptiveCards.AdaptiveCard.actionTypeRegistry
  • For Elements use AdaptiveCards.AdaptiveCard.elementTypeRegistry

For example, to override the rendering of a Input.Date element:

AdaptiveCards.AdaptiveCard.elementTypeRegistry.registerType("Input.Date", () => { return new DateInput(); }); 

To override an Action:

AdaptiveCards.AdaptiveCard.actionTypeRegistry.registerType("Action.OpenUrl", () => { return new OpenUrlAction(); });