Accessibility tips for Adaptive Cards

Copilot Studio agents work well with screen readers on Windows, such as NonVisual Desktop Access (NVDA) and Job Access with Speech (JAWS). To optimize accessibility, consider these tips.

Screen readers

For screen reader and keyboard navigation accessibility of Adaptive Cards, here's what matters most.

  • Always include the "label" property: The "label" property is what screen readers announce when a user focuses on an input. Without it, screen readers might just say "edit field" with no context. Screen readers often don't read placeholders, and they disappear once the user starts typing. Therefore, avoid relying on them to assist with accessibility.

    {
  "type": "Input.Text",
  "id": "middleName",
  "label": "Middle name (optional)",
  "placeholder": "Enter your middle name"
}

  • Use "inputStyle" and "style" thoughtfully: Avoid custom styling that removes focus indicators. The default focus ring is what keyboard users rely on to know where they are on the card.

  • Use "isRequired" and "errorMessage" for readers: Even for optional fields, a clear "errorMessage" helps screen readers communicate validation feedback.

    {
  "type": "Input.Text",
  "id": "middleName",
  "label": "Middle name (optional)",
  "isRequired": false,
  "errorMessage": "Please enter a valid middle name"
}

  • Logical tab order: Adaptive Cards follow Document Object Model (DOM) order for tab navigation, so structure the JSON representation of your card in the order you want users to tab through. Avoid using "ColumnSet" layouts that create a visually logical order but a confusing tab order for keyboard users.

  • Action buttons are keyboard accessible by default: Properties such as "Action.Submit" and "Action.OpenUrl" are natively focusable. Make sure your title is descriptive rather than something vague like "Click here" because screen readers read the title aloud.

  • Add "type": "TextBlock" for instructions: If a section of optional fields needs context, set "type" as "TextBlock" before those fields. Screen readers read fields in sequence, giving users the context they need before reaching the inputs.

    {
  "type": "TextBlock",
  "text": "The following fields are optional. You can skip them if not applicable.",
  "wrap": true
}

  • Avoid "isVisible": "false" for accessibility scenarios: Screen readers skip hidden elements entirely. If accessibility is the priority, keep optional fields visible. If you must hide them, ensure the toggle has a clear, descriptive label.

  • Pro tip for testing in Microsoft Teams: Due to slight differences in Microsoft Teams support for Adaptive Cards, we recommend that you use the built-in Windows Narrator or NVDA to validate the tab order and that announcements work as expected.

Specific schema properties

Here are some specific properties in the Adaptive Cards schema that can help improve accessibility.

The "label" property

The "label" property is critical for screen readers. By having a connection between labels and inputs, renderer libraries can set the necessary properties to allow users of assistive technologies, such as screen readers, to interact correctly with inputs inside Adaptive Cards.

Learn more in Input.Text.

Why "label" beats "placeholder" for accessibility?

We recommend using the "label" property for tagging Adaptive Cards input parameters, instead of the "placeholder" property. It's a simple and concise way of labeling inputs for card authors.

Using "TextBlock" properties as labels prevents you from enforcing proximity between inputs and labels. By using the "label" property, you can ensure that both visual elements are rendered next to each other, which helps users who need screen magnifiers.

Learn more in Input Validation.

Use "errorMessage" for validation feedback

The "errorMessage" property is available for all input types to specify the message to show when a user enters a value that isn't valid.

Learn more in Input Validation.

TextBlock with "style": "heading" for accessibility structure

Using "style": "heading" applies the default heading styling and marks the TextBlock element as a heading for accessibility.

Learn more in TextBlock Element.

Action buttons—"tooltip" for narration

The "Action.ToggleVisibility" action supports a "tooltip" property that defines text that appears when the user hovers the mouse over the action. Narration software reads this text.

Learn more in Action.ToggleVisibility.

Caution with "isVisible": "false" for Input elements

Keep input elements with validation visible. Input elements with validation under "Action.ToggleVisibility" might generate confusion when hidden input parameters aren't valid.

Learn more in Action.ToggleVisibility.

The "labelPosition" property for Input.ChoiceSet

For "Input.ChoiceSet", the "labelPosition" property determines the position of the label, either inline or above (default).

Learn more in Input.ChoiceSet.

  • Last updated on