Designing Adaptive Cards for your Microsoft Teams app

An Adaptive Card contains a freeform body of card elements and optional set of actions. Adaptive Cards are actionable snippets of content that you can add to a conversation through a bot or message extension. Using text, graphics, and buttons, these cards provide rich communication to your audience.

The Adaptive Card framework is used across many Microsoft products, including Teams. You can send cards inside messages to users via bots or message extensions. Users can also take actions on cards when present.

Overview example of an Adaptive Card.

Microsoft Teams UI Kit

You can find more comprehensive design guidelines for Adaptive Cards in Teams, including elements that you can grab and modify as needed, in the Microsoft Teams UI Kit. The UI kit also covers essential topics such as theming, accessibility, and responsive sizing.

Adaptive Cards designer

You also can start designing your Adaptive Cards directly in the browser.

Types of Adaptive Cards

Hero

Our largest card. Use for sharing articles or scenarios where an image tells most of the story.

Mobile

Example shows an Adaptive Card hero card on mobile.

Desktop

Example shows an Adaptive Card hero card.

Thumbnail

Use for sending a simple actionable message.

Mobile

Example shows an Adaptive Card thumbnail card on mobile.

Desktop

Example shows an Adaptive Card thumbnail card.

List

Use in scenarios where you want the user to pick an item from a list, but the items don’t need a lot of explanations.

Mobile

Example shows an Adaptive Card list card on mobile.

Desktop

Example shows an Adaptive Card list card.

Digest

Use for news digests and round-up posts. Note: We recommend the thumbnail card for a single update or news item.

Mobile

Example shows an Adaptive Card digest card on mobile.

Desktop

Example shows an Adaptive Card digest card.

Media

Use when you want to combine text and media, like audio or video.

Mobile

Example shows an Adaptive Card media card on mobile.

Desktop

Example shows an Adaptive Card media card.

People

Use when you want to efficiently communicate the individuals involved in a task.

Mobile

Example shows an Adaptive Card people card on mobile.

Desktop

Example shows an Adaptive Card people card.

Request ticket

Use to get quick inputs from a user to automatically create a task or ticket.

Mobile

Example shows an Adaptive Card request ticket card on mobile.

Desktop

Example shows an Adaptive Card request ticket card.

ImageSet

Use to send multiple image thumbnails.

Mobile

Example shows an Adaptive Card image set card on mobile.

Desktop

Example shows an Adaptive Card image set card.

ActionSet

Use when you want to the user to select a button, then gather addition user input from the same card.

Mobile

Example shows an Adaptive Card action set card on mobile.

Desktop

Example shows an Adaptive Card action set card.

ChoiceSet

Use to gather multiple inputs from the user.

Mobile

Example shows an Adaptive Card choice set card on mobile.

Desktop

Example shows an Adaptive Card choice set card.

Anatomy

Adaptive Cards have a lot of flexibilities. But at minimum, we strongly suggest including the following components in every card.

Mobile

Example shows Adaptive Card anatomy on mobile.

Counter Description
A Header: Make your headers clear and concise.
B Body copy: Convey details that are either too long or not important enough to include in the header.
C Primary actions: As a best practice, include 1-3 primary actions. You can have up to six.

Desktop

EExample shows Adaptive Card anatomy.

Counter Description
A Header: Make your headers clear and concise.
B Body copy: Convey details that are either too long or not important enough to include in the header.
C Primary actions: As a best practice, include 1-3 primary actions. You can have up to six.

Best practices

Cards designed for a narrow screen scale well on wider screens (the opposite isn't true). You should also assume users won't only view your cards on desktop.

Column layouts

Use ColumnSet to format your card content into a table or grid. There are several options for formatting column width. These guidelines help you understand when to use each one.

  • "width": "auto": Sizes each column in the ColumnSet to fit whatever app content you include in that column.
    • Do: Use when you have content of varying width and don't need to prioritize a specific column.
    • Do: For each TextBlock, set "wrap": true since text doesn't wrap by default.
    • Don't: Set "width": "auto" for every column container. For example, if you have an input and button side by side, the button might get cut off on some screens. Instead, set auto for the column with buttons and other content that must always be completely visible.
  • "width": "stretch": Sizes columns based on the available ColumnSet width. When multiple columns use the "stretch" value, they equally share the available width.
    • Do: Use with one column if all your other columns have a static width. For example, you have thumbnail images in one column that are all 50 pixels wide.
  • "width": "<number>": Sizes columns using a proportion of the available ColumnSet width. For example, if you set three columns with "width": "1", "width": "4", and "width": "5", the columns will take up 10, 40, and 50 percent of the available width.
  • "width": "<number>px": Sizes columns to a specific pixel width. This approach is useful when creating tables.
    • Do: Use when the width of what you're displaying doesn't need to change (for example, numbers and percentages).
    • Don't: Accidentally exceed the width of what the card can display. Remember, available screen width depends on the device. Teams mobile also doesn't support horizontal scrolling like Teams desktop.

Example: Knowing when to stretch columns

Do: In this screen, there are two columns at the bottom of the card. The input component width is set to stretch, while the Select button width is set to auto. This ensures the button remains completely in view.

The screenshot shows how to set column width for Adaptive Cards.

Don't: In this screen, both columns have width set to auto. This causes the Select button on the right to be cut off slightly compared to the input.

The screenshot shows how not to set column width in Adaptive Cards.

Example: Using fewer columns

Do: Layouts tend to display better on mobile with fewer columns.

The screenshot shows the right number of columns in Adaptive Cards.

Don't: Using too many columns can clutter your card content on mobile.

The screenshot shows how to many columns can negatively affect Adaptive Card layout.

Example: Fixed width has its place

When the the size of something you're displaying doesn't need to change, set you columns to a specific pixel width. This example shows the left column sized at 50 pixels, while the descriptions next to the thumbnails stretch the length of the card.

The screenshot shows how to set column width in Adaptive Cards.

Text

Whether you're using TextBlock, ColumnSet, or Input.ChoiceSet, set the wrap property to true so your card text doesn't truncate on mobile.

Example: Making sure text don't truncate

Do: In this screen, the card has a wrap property set to true. This allows the text to fit to any screen size.

The screenshot shows how to wrap text in Adaptive Cards.

Don't: In this screen, the card doesn't use the wrap property, so the text cuts off on a mobile screen.

The screenshot shows what can happen if you don't wrap text in Adaptive Cards.

Containers

A Container allows you to group a set of related elements together.

  • Do: Use the style property to emphasize a container.
  • Do: Use the selectAction property to associate an action with the other elements in the container.
  • Do: Use the Action.ToggleVisibility property to make a group of elements collapsible.
  • Don't: Use containers for any reason other than previously mentioned.

Images

Follow these guidelines when including images in your cards.

  • Do: Design images for high DPI screens to avoid pixelation. It's better to display a 100 x 100 pixel image at 50 x 50 pixels than the other way around.
  • Do: If you need to control the exact size of your images, use the width and height properties.
  • Don't: Include padding with your images. This typically introduces undesirable spacing and layout issues.
  • Regarding background color:
    • Do: Use transparent backgrounds so that your images adapt to any Teams theme.
    • Don't: Include a fixed background color unless a specific color must be visible to your users.
    • Don't: Add a background color to a TextBlock that hurts readability. For example, if your background is dark, use a lighter text color and vice versa.

Actions

The screenshot shows best practice about how you should include only a small set of actions on an Adaptive Card.

Do: Use up to six primary actions

While Adaptive Cards can support six primary actions, most cards don’t need that. Actions should be clear, concise, and straight forward. Less is more.

The screenshot shows best practice about how not to overwhelm users with too many actions on an Adaptive Card.

Don't: Use more than six primary actions

Adaptive Cards should present quick, actionable content. Too many actions can overwhelm a user.

Frequency

The screenshot shows best practice about Adaptive Card frequency.

Do: Be concise

It's easy to send multiple cards into a conversation, but once cards scroll out of view, they become less useful. Try to limit yourself to the essentials. This is especially true in a channel where users have less tolerance for what they perceive as "noise".

See also