Format cards in Teams

The following table provides the supported styles for Textblock, Fact.Title, and Fact.Value:

The following Markdown tags aren't supported:

• Headers
• Tables
• Images
• Preformatted text
• Blockquotes

Newlines for Adaptive Cards

You can use the \r or \n escape sequences for newlines in lists. Using \n\n in lists causes the next element in the list to be indented. If you require newlines elsewhere in the TextBlock, use \n\n.

Mobile and desktop differences for Adaptive Cards

On the desktop, Adaptive Card Markdown formatting appears as shown in the following image in both web browsers and in the Teams client application:

On iOS, Adaptive Card Markdown formatting appears as shown in the following image:

On Android, Adaptive Card Markdown formatting appears as shown in the following image:

For more information, see text features in Adaptive Cards.

Adaptive Cards format sample

The following code shows an example of Adaptive Cards formatting:

{
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.0",
    "body": [
        {
            "type": "TextBlock",
            "text": "This is some **bold** text"
        },
        {
            "type": "TextBlock",
            "text": "This is some _italic_ text"
        },
        {
            "type": "TextBlock",
            "text": "- Bullet \r- List \r",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "1. Numbered\r2. List\r",
            "wrap": true
        },
        {
            "type": "TextBlock",
            "text": "Check out [Adaptive Cards](https://adaptivecards.io)"
        }
    ]
}

Adaptive Cards support emojis. The following card payload shows an Adaptive Card with an emoji:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Publish Adaptive Card with emojis 🥰",
          "weight": "bolder",
          "size": "medium"
        }
      ]
    }
  ]
}

Mention support within Adaptive Cards

You can add @mentions within an Adaptive Card body for bots and message extension responses. To add @mentions in cards, follow the same notification logic and rendering as that of message based mentions in channel and group chat conversations.

Bots and message extensions can include mentions within the card content in TextBlock and FactSet elements.

To include a mention in an Adaptive Card, your app needs to include the following elements:

• <at>username</at> in the supported Adaptive Card elements.
• The mention object inside of an msteams property in the card content includes the Teams user ID of the user being mentioned.
• The userId is unique to your bot ID and a particular user. It can be used to @mention a particular user. The userId can be retrieved using one of the options mentioned in get the user ID.

Sample Adaptive Card with a mention

The following code shows an example of Adaptive Card with a mention:

{
  "contentType": "application/vnd.microsoft.card.adaptive",
  "content": {
    "type": "AdaptiveCard",
    "body": [
      {
        "type": "TextBlock",
        "text": "Hi <at>John Doe</at>"
      }
    ],
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0",
    "msteams": {
      "entities": [
        {
          "type": "mention",
          "text": "<at>John Doe</at>",
          "mentioned": {
            "id": "29:123124124124",
            "name": "John Doe"
          }
        }
      ]
    }
  }
}

Microsoft Entra Object ID and UPN in user mention

Teams platform allows you to mention users with their Microsoft Entra Object ID and User Principle Name (UPN), in addition to the existing mention IDs. Bots with Adaptive Cards and Connectors with Incoming Webhooks support the two user mention IDs.

The following table describes the newly supported user mention IDs:

User mention in bots with Adaptive Cards

Bots support user mention with the Microsoft Entra Object ID and UPN, in addition to the existing IDs. The support for two new IDs is available in bots for text messages, Adaptive Cards body, and message extension response. Bots support the mention IDs in conversation and invoke scenarios. The user gets activity feed notification when being @mentioned with the IDs.

Example

Example for user mention in bots with Adaptive Cards as follows:

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0",
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "text": "Hi <at>Adele UPN</at>, <at>Adele Microsoft Entra ID</at>"
    }
  ],
  "msteams": {
    "entities": [
      {
        "type": "mention",
        "text": "<at>Adele UPN</at>",
        "mentioned": {
          "id": "AdeleV@contoso.onmicrosoft.com",
          "name": "Adele Vance"
        }
      },
      {
        "type": "mention",
        "text": "<at>Adele Microsoft Entra ID</at>",
        "mentioned": {
          "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
          "name": "Adele Vance"
        }
      }
    ]
  }
}

Following image illustrates the user mention with Adaptive Card in Bot:

User mention in Incoming Webhook with Adaptive Cards

Incoming webhooks start to support user mention in Adaptive Cards with the Microsoft Entra Object ID and UPN.

Example

Example for user mention in Incoming Webhook as follows:

{
    "type": "message",
    "attachments": [
        {
        "contentType": "application/vnd.microsoft.card.adaptive",
        "content": {
            "type": "AdaptiveCard",
            "body": [
                {
                    "type": "TextBlock",
                    "size": "Medium",
                    "weight": "Bolder",
                    "text": "Sample Adaptive Card with User Mention"
                },
                {
                    "type": "TextBlock",
                    "text": "Hi <at>Adele UPN</at>, <at>Adele Microsoft Entra ID</at>"
                }
            ],
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.0",
            "msteams": {
                "entities": [
                    {
                        "type": "mention",
                        "text": "<at>Adele UPN</at>",
                        "mentioned": {
                          "id": "AdeleV@contoso.onmicrosoft.com",
                          "name": "Adele Vance"
                        }
                      },
                      {
                        "type": "mention",
                        "text": "<at>Adele Microsoft Entra ID</at>",
                        "mentioned": {
                          "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
                          "name": "Adele Vance"
                        }
                      }
                ]
            }
        }
    }]
}

Following image illustrates user mention in Incoming Webhook:

People icon in an Adaptive Card

People icon helps users to view the images of users in an Adaptive Card. You can insert an image and apply all the properties supported on images.

There are two types of people icons that are supported in an Adaptive Card:

• Persona: If you want to show a single user in an Adaptive Card, it displays the people icon and the name of the user.

  The following JSON code is an example of a Persona card:

  {
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.0.0",
    "body": [
  {
        "type": "TextBlock",
        "text": "Persona",
        "weight": "bolder"
      },
      {
        "type": "Component",
        "name": "graph.microsoft.com/user",
        "view": "compact",
        "properties": {
          "id": "65f50003-e15d-434a-9e14-0fcfeb3d7817",
          "displayName": "Daniela Mandera",
          "userPrincipalName": "damandera@microsoft.com"
        }
      }
    ]
  }
  

• Persona Set: If you want to show multiple users in an Adaptive Card, it displays only the people icon of the users.

  The following JSON code is an example of a Persona Set:

  {
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "type": "AdaptiveCard",
    "version": "1.0.0",
    "body": [
      {
        "type": "TextBlock",
        "text": "Persona Set",
        "weight": "bolder"
      },
      {
        "type": "Component",
        "name": "graph.microsoft.com/users",
        "view": "compact",
        "properties": {
          "users": [
            {
              "id": "65f50003-e15d-434a-9e14-0fcfeb3d7817",
              "displayName": "Daniela Mandera",
              "userPrincipalName": "damandera@microsoft.com"
            },
            {
              "id": "65f50003-e15d-434a-9e14-0fcfeb3d7817",
              "displayName": "Daniela Mandera",
              "userPrincipalName": "damandera@microsoft.com"
            }
          ]
        }
      }
    ]
  }
  

  Note

  You can't customize the style of the Persona and Persona Set in an Adaptive Card.

The following image is an example of the people icon in an Adaptive Card:

Schema

The following table lists the properties of the Component element:

Adaptive Components are high-level components powered by templating and native Adaptive Card elements. The type component can be used anywhere inside the card body and the component data is defined in the properties attribute. The component data under properties is passed directly to the component. The properties property defines the format for Persona and Persona Set and all other properties under properties is ignored by component type in the Adaptive Card schema.

Your bot can query for the list of members and their basic user profiles, including Teams user IDs and Microsoft Entra information, such as name, id, and userPrincipalName. For more information, see Fetch the roster or user profile.

The following images show the people icon in an Adaptive Card on Teams desktop and mobile clients:

Desktop client:

When a user hovers on a people icon, the people card of that user is displayed.

Mobile client

When a user selects a people icon, it displays the people card of that user.

Information masking in Adaptive Cards

Use the information masking property to mask specific information, such as password or sensitive information from users within the Adaptive Card Input.Text input element.

To mask information in Adaptive Cards, add the style property to type input.text, and set its value to Password.

Sample Adaptive Card with masking property

The following code shows an example of Adaptive Card with masking property:

{
    "type": "Input.Text",
    "id": "secretThing",
    "style": "password",
},

The following image is an example of masking information in Adaptive Cards:

Full width Adaptive Card

You can use the msteams property to expand the width of an Adaptive Card and make use of extra canvas space. The next section provides information on how to use the property.

Construct full width cards

To make a full width Adaptive Card, the width object in msteams property in the card content must be set to Full.

Sample Adaptive Card with full width

To make a full width Adaptive Card, your app must include the elements from the following code sample:

{
    "type": "AdaptiveCard",
    "body": [{
        "type": "Container",
        "items": [{
            "type": "TextBlock",
            "text": "Digest card",
            "size": "Large",
            "weight": "Bolder"
        }]
    }],

    "msteams": {
        "width": "Full"
    },
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2"
}

The following image shows a full width Adaptive Card:

The following image shows the default view of an Adaptive Card when you haven't set the width property to Full:

Adaptive Card responsive layout

Adaptive Cards automatically adapt their look and feel to the host application's style, but have a fixed layout that remains the same across Teams mobile and desktop clients. You must design your Adaptive Cards to look great on any device in order to provide an enhanced user experience across chat, channels, and meeting chat. In this article, you'll learn about designing responsive Adaptive Cards.

Adaptive Card responsive layout helps you to design cards with different layouts that target different card widths.

Design responsive Adaptive Cards

Use the targetWidth property on any element to:

• Show or hide any element based on the card's width.

• Set different target widths on different elements to create different layouts.

  The following table lists the available targetWidth values:

  Value	Description
  veryNarrow	The element is visible when the Adaptive Card's width is very narrow such as in a meeting chat.
  narrow	The element is visible when the Adaptive Card's width is narrow such as on a mobile phone in portrait mode.
  standard	The element is visible when the Adaptive Card's width is standard such as on a mobile phone in landscape mode, on a tablet in portrait mode, or in a chat on desktop.
  wide	The element is visible when the Adaptive Card's width is wide such as on a tablet in landscape mode, in a channel or chat on desktop when you set your card to be full width.

  You can also set the targetWidth property to make an element visible for a range of card widths using the atLeast and atMost prefixes. For example, you can make an element visible only when the card width is 'standard or above' or only when the card width is 'narrow or below'. The following table provides guidance on how to make an element visible for a range of card widths:

  Example	Description
  "targetWidth": "atLeast:standard"	The element is visible only when the Adaptive Card's width is at least standard, which means standard or wide.
  "targetWidth": "atMost:narrow"	The element is visible only when the Adaptive Card's width is at most narrow, which means very narrow or narrow.

  Note

  You don't have to set targetWidth on all elements. If you don't set targetWidth for an element, the element is always visible irrespective of the card's width.

The following are JSON samples for an Adaptive Card designed without using targetWidth and modified to usetargetWidth:

• Adaptive Card designed without using targetWidth:

  {
    "type": "AdaptiveCard",
    "body": [
      {
        "type": "ColumnSet",
        "columns": [
          {
            "type": "Column",
            "items": [
              {
                "type": "Image",
                "style": "Person",
                "url": "https://aka.ms/AAp9xo4",
                "size": "Small"
              }
            ],
            "width": "auto"
          },
          {
            "type": "Column",
            "spacing": "medium",
            "verticalContentAlignment": "center",
            "items": [
              {
                "type": "TextBlock",
                "weight": "Bolder",
                "text": "David Claux",
                "wrap": true
              }
            ],
            "width": "auto"
          },
          {
            "type": "Column",
            "spacing": "medium",
            "items": [
              {
                "type": "TextBlock",
                "text": "Platform Architect",
                "isSubtle": true,
                "wrap": true
              }
            ],
            "width": "stretch",
            "verticalContentAlignment": "center"
          }
        ]
      }
    ],
    "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.5"
  }
  
  

  The following images show the rendering of the Adaptive Card for different card widths:

  • When the card's width is wide, the card looks good.

    

  • When the card's width is standard or narrow, the role is squeezed.

    

  • When the card's width is very narrow, the name and role are significantly squeezed.

    

• Adaptive Card updated to be responsive using targetWidth:

    {
      "type": "AdaptiveCard",
      "body": [
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "targetWidth": "atLeast:narrow",
              "items": [
                {
                  "type": "Image",
                  "style": "Person",
                  "url": "https://aka.ms/AAp9xo4",
                  "size": "Small"
                }
              ],
              "width": "auto"
            },
            {
              "type": "Column",
              "spacing": "medium",
              "verticalContentAlignment": "center",
              "items": [
                {
                  "type": "TextBlock",
                  "weight": "Bolder",
                  "text": "David Claux",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "targetWidth": "atMost:narrow",
                  "spacing": "None",
                  "text": "Platform Architect",
                  "isSubtle": true,
                  "wrap": true
                }
              ],
              "width": "auto"
            },
            {
              "type": "Column",
              "targetWidth": "atLeast:standard",
              "spacing": "medium",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Platform Architect",
                  "isSubtle": true,
                  "wrap": true
                }
              ],
              "width": "stretch",
              "verticalContentAlignment": "center"
            }
          ]
        }
      ],
      "$schema": "https://adaptivecards.io/schemas/adaptive-card.json",
      "version": "1.5"
    }
  

  Let's see how the same Adaptive Card renders after using the targetWidth property for different card widths:

  • When the card's width is wide, the card still looks good.

    

  • When the card's width is standard or narrow, the role is moved under the name as there's no horizontal space to show them side-by-side.

    

  • When the card's width is very narrow, we can hide the image and only keep the most meaningful information.

    

For more information on how to design an Adaptive Card, see designing Adaptive Cards for your Teams app.

Typeahead support

Within the Input.Choiceset schema element, asking users to filter and select a sizeable number of choices can significantly slow down task completion. Typeahead support within Adaptive Cards can simplify input selection by narrowing or filtering the set of input choices as the user types the input.

To enable typeahead within the Input.Choiceset, set style to filtered and ensure isMultiSelect is set to false.

Sample Adaptive Card with typeahead support

The following code shows an example of Adaptive Card with typeahead support:

{
   "type": "Input.ChoiceSet",
   "label": "Select a user",
   "isMultiSelect": false,
   "choices":  [
      { "title": "User 1", "value": "User1" },
      { "title": "User 2", "value": "User2" }
    ],
   "style": "filtered"
}

Stageview for images in Adaptive Cards

In an Adaptive Card, you can use the msteams property to add the ability to display images in Stageview selectively. When users hover over the images, they can see an expand icon, for which the allowExpand attribute is set to true. The following code is an example of the msteams property:

{
    "type": "AdaptiveCard",
     "body": [
          {
            "type": "Image",
            "url": "https://picsum.photos/200/200?image=110",
            "msTeams": {
              "allowExpand": true
            }
          }
     ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.2"
}

When users hover over the image, an expand icon appears at the upper-right corner as shown in the following image:

The image appears in Stageview when the user selects the expand icon as shown in the following image:

In the Stageview, users can zoom in and zoom out of the image. You can select the images in your Adaptive Card that must have this capability.

Connector cards support limited Markdown and HTML formatting.

Style	Example	Markdown
Bold	text	**text**
Italic	text	*text*
Header (levels 1–3)	Text	### Text
Strikethrough	text	~~text~~
Unordered list	text text	- Item 1\r- Item 2\r- Item 3
Ordered list	text text	1. Green\r2. Orange\r3. Blue
Preformatted text	text	preformatted text
Blockquote	>blockquote text	>blockquote text
Hyperlink	Bing	[Bing](https://www.bing.com/)
Image link		

In connector cards, newlines are rendered for \n\n, but not for \n or \r.

Mobile and desktop differences for connector cards

On the desktop, Markdown formatting for connector cards appears as shown in the following image:

On iOS, Markdown formatting for connector cards appears as shown in the following image:

Connector cards using Markdown for iOS include the following issues:

• The iOS client for Teams doesn't render Markdown or HTML inline images in connector cards.
• Blockquotes are rendered as indented but without a gray background.

On Android, Markdown formatting for connector cards appears as shown in the following image:

Format example for Markdown connector cards

The following code shows an example of formatting for Markdown connector cards:

{
  "contentType": "application/vnd.microsoft.teams.card.o365connector",
  "content": {
    "@type": "MessageCard",
    "@context": "https://schema.org/extensions",
    "summary": "Summary",
    "title": "Connector Card Markdown formatting",
    "sections": [
        {
            "text": "This is some **bold** text"
        },
        {
            "text": "This is some _italic_ text"
        },
        {
            "text": "# Header 1\r## Header 2\r### Header 3"
        },
        {
            "text": "- Bullet \r- List \r"
        },
        {
            "text": "1. Numbered\r1. List \r"
        },
        {
            "text": "Link: [Bing](https://www.bing.com)"
        },
        {
            "text": "embedded image link: ![Duck on a rock](https://aka.ms/Fo983c)"
        },
        {
            "text": "`preformatted text`"
        },
        {
            "text": "Newlines (backslash n, backslash n):\n\nline a\n\nline b\n\nline c"
        },
        {
            "text": ">This is a blockquote"
        }
     ]
  }
}

When a user selects the overflow menu on a desktop, the buttons that are set as secondary appear in the Adaptive Card.

When a user selects the overflow menu on mobile, Adaptive Card displays the buttons that are defined. There's an integrated sheet that displays an overflow menu with card related tasks with a message option. A long press on any message displays a list of related messages. This option is available only for actions.

Connector cards support limited Markdown and HTML formatting.

Style	Example	HTML
Bold	text	<strong>text</strong>
Italic	text	<em>text</em>
Header (levels 1–3)	Text	<h3>Text</h3>
Strikethrough	text	<strike>text</strike>
Unordered list	text text	<ul><li>text</li><li>text</li></ul>
Ordered list	text text	<ol><li>text</li><li>text</li></ol>
Preformatted text	text	<pre>text</pre>
Blockquote	text	<blockquote>text</blockquote>
Hyperlink	Bing	<a href="https://www.bing.com/">Bing</a>
Image link		<img src="https://aka.ms/Fo983c" alt="Duck on a rock"></img>

In connector cards, newlines are rendered in HTML using the <p> tag.

Mobile and desktop differences for connector cards

On the desktop, HTML formatting for connector cards appears as shown in the following image:

On iOS, HTML formatting appears as shown in the following image:

Connector cards using HTML for iOS include the following issues:

• Inline images aren't rendered on iOS using either Markdown or HTML in connector cards.
• Preformatted text is rendered but doesn't have a gray background.

On Android, HTML formatting appears as shown in the following image:

Format sample for HTML connector cards

The following code shows an example of formatting for HTML connector cards:

{
  "contentType": "application/vnd.microsoft.teams.card.o365connector",
  "content": {
    "@type": "MessageCard",
    "@context": "https://schema.org/extensions",
    "summary": "Summary",
    "title": "Connector Card HTML formatting",
    "sections": [
        {
            "text": "This is some <strong>bold</strong> text"
        },
        {
            "text": "This is some <em>italic</em> text"
        },
        {
            "text": "This is some <strike>strikethrough</strike> text"
        },
        {
            "text": "<h1>Header 1</h1>\r<h2>Header 2</h2>\r <h3>Header 3</h3>"
        },
        {
            "text": "bullet list <ul><li>text</li><li>text</li></ul>"
        },
        {
            "text": "ordered list <ol><li>text</li><li>text</li></ol>"
        },
        {
            "text": "hyperlink <a href=\"https://www.bing.com/\">Bing</a>"
        },
        {
            "text": "embedded image <img src=\"https://aka.ms/Fo983c\" alt=\"Duck on a rock\"></img>"
        },
        {
            "text": "preformatted text <pre>text</pre>"
        },
        {
            "text": "Paragraphs <p>Line a</p><p>Line b</p>"
        },
        {
            "text": "<blockquote>Blockquote text</blockquote>"
        }
     ]
  }
}

HTML tags are supported for simple cards, such as the hero and thumbnail cards. Markdown isn't supported.

Style	Example	HTML
Bold	text	<strong>text</strong>
Italic	text	<em>text</em>
Header (levels 1–3)	Text	<h3>Text</h3>
Strikethrough	text	<strike>text</strike>
Unordered list	text text	<ul><li>text</li><li>text</li></ul>
Ordered list	text text	<ol><li>text</li><li>text</li></ol>
Preformatted text	text	<pre>text</pre>
Blockquote	text	<blockquote>text</blockquote>
Hyperlink	Bing	<a href="https://www.bing.com/">Bing</a>
Image link		<img src="https://aka.ms/Fo983c" alt="Duck on a rock"></img>

Mobile and desktop differences for simple cards

As there are resolution differences between the desktop and mobile platform, formatting is different between the desktop and the mobile version of Teams.

On the desktop, HTML formatting appears as shown in the following image:

On iOS, HTML formatting appears as shown in the following image:

Character formatting, such as bold and italic isn't rendered on iOS.

On Android, HTML formatting appears as shown in the following image:

Character formatting, such as bold and italic displays correctly on Android.

Format example for simple cards

The images in the previous section were created using Teams App Studio, where the text property of a hero card is set to the following string:

<p>bold: <strong>Bold Text</strong></p><p>italic: <em>Italic Text</em></p><p>strikethrough: <strike>Strikethrough text</strike></p><h1>Header 1</h1><h2>Header 2</h2><h3>Header 3</h3><p>bullet list: <ul><li>text</li><li>text</li></ul></p><p>ordered list: <ol><li>text</li><li>text</li></ol></p><pre>preformatted text</pre><blockquote>blockquote text</blockquote></p><p>hyperlink: <a href=\"https://www.bing.com/\">Bing</a></p><p>embedded image: <img src=\"https://aka.ms/Fo983c\" alt=\"Duck on a rock\"></img></p>

You can test formatting in your own cards by modifying this code.