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.

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"
        }
    ]
};

// define your render options
var renderOptions = {

    // a Host Config defines the style and behavior of all cards
    hostConfig: {
        "fontFamily": "Segoe UI, Helvetica Nue, sans-serif"
    },

    // the action handler is invoked when actions are pressed
    onExecuteAction: function (action) { alert("Ow!"); },

    // For markdown support you need a third-party library
    // E.g., to use markdown-it include the script and add the following:
    // <!-- <script type="text/javascript" src="https://unpkg.com/markdown-it/dist/markdown-it.js"></script> -->
    //processMarkdown: function (text) { return markdownit().render(text); }
};


// render the card to HTML
var renderedCard = AdaptiveCards.renderCard(card, renderOptions);

// now put it somewhere!
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(); });