Tooltip property on Actions (extra hint to the user)

Requirements

1. A tooltip is displayed when the mouse hovers over a clickable affordance such as a button, an image or a container.
2. It is possible to define what text is displayed in that tooltip in the JSON payload of the card
3. If both tooltip and title are specified, tooltip “wins”

Design options

Option 1 (Selected)

Introduce a toolTip property on all action types. Any visual element that is associated with an action that has its tooltip set will display that tooltip. That means:

• Buttons, including the button representing the inlineAction of a TextBlock

• Images, Containers or even the whole card with a selectAction that has its toolTip property set

Examples

{
   "type": "Action.OpenUrl",
   "title": "View user profile",
   "tooltip": "Learn more about this user"
}

Note that a selectAction’s iconUrl is ignored. If tooltip is not present on a select action but title is, the title will be used as the tooltip. title will be ignored if tooltip is present.

{
   "type": "Container",
   "items": [
      { 
         "type": "TextBlock", 
         "text": "View user profile" 
      }
    ],
   "selectAction": {
      "type": "Action.OpenUrl",
      "url": "https://adaptivecards.io",
      "tooltip": "Learn more about this user"
   }
}

Accessibility considerations

The current expected accessibility behavior for actions is that the title property is read by screen readers. In the case of a select action, if title is unset, the contents of the container the select action is on will be read instead.

With the addition of the tooltip property, that behavior will be supplemented with the text from tooltip if present. In the case that both title and tooltip are set, both should be read by screen readers navigating to the given action. If a select action has tooltip but no title, the contents of the container should be read, followed by the tooltip text.

An accessibility specific property additional to title, which would allow card authors to set text to the screen readers that is different than the text displayed on the button, may be added in the future. In that case the accessibility property would override title (and select action contents) to be read, but would still be followed by the tooltip text. Adding that new property is out of scope for this work.

Option 2 (Tooltips on all elements - possible future work)

Extend option 1 to all elements to make it possible to define a tooltip on anything in a card by adding a toolTip property to all element types. This makes it possible, for instance, to create scenarios such as this one:

In the above image, the user hovers over a non clickable image and gets a tooltip providing additional information about “Element ID”

This option introduces the corner case of an element and its associated action (say an Image with a selectAction) both having a tooltip set. In that case, the selectAction’s tooltip wins and the Image’s tooltip is ignored.

Example

{
   "type": "Image",
   "url": "http://3.bp.blogspot.com/-ChgHNWjiuVk/Uf_qp8lqN7I/AAAAAAAACOc/J2RuNaBVkNY/s1600/Eiffel+tower.jpg",
   "altText": "The Eiffel Tower in Paris",
   "tooltip": "The Eiffel Tower is a wrought-iron lattice tower on the Champ de Mars in Paris, France. It is named after the engineer Gustave Eiffel, whose company designed and built the tower."
}

Note: in the above sample, you can see that both the altText and the toolTip properties of the Image are set. The altText property on images is used as a replacement for the image itself if the image cannot be displayed. It is not meant to be used as a tooltip. There is no redundancy issue between the two properties.

Option 3 (not recommended)

Use Action.title as the tooltip. While there would be no schema change required for the tooltip itself, this option still requires the addition of a property to allow the card author to define how a button needs to be displayed: some actions may have an iconUrl but no title, in which case they need to be displayed as just an icon. If title was to be used as a tooltip, there would have to be a way for the card author to say “I’m putting a title here but I don’t want it displayed”.

I strongly believe option 1 is a stronger option than this one, so I’m not going to spec it further.

Other considerations

Should we allow Markdown in tooltips?

No. Markdown in tooltips would be great, but supporting that feature would likely be a lot more expensive because native tooltip support might not cut it (that would be true in HTML) requiring the implementation of custom tooltip visuals and positioning.

Displaying tooltips

It is up to each and every platform to display the tooltips whichever way is appropriate. Tooltips may even be ignored on mobile if there is not great way to surface them (beyond the scope of this speclet.)

To ease implementation, native tooltips will be used where available, and there is no requirement for a renderer to allow host applications to customize the appearance of tooltips.

Should there be a way for hosts to disable tooltips?

I don’t think so. Thoughts welcome.
If we did allow hosts to disable tooltips, we’d add a flag somewhere in HostConfig.

[anna-dingler]

@bandtank tooltip property for actions was added to the schema in version 1.5.

https://adaptivecards.io/explorer/Action.OpenUrl.html

[robhung]

Using version 1.5 of AdaptiveCard with the following code:

actions: [
    {
      type: "Action.OpenUrl",
      title: "🖼️ How link previews work",
      tooltip: "test",
      url: "https://test.com",
    },
]

And I really wish there was a way to remove the url in the tooltip, see screenshot below

By default, if you don’t define a tooltip property, it will use both the title and url - there is no option to hide it completely?