Draft tooltip design pattern

[mcking65]

The tooltip design pattern is at:
http://w3c.github.io/aria-practices/#tooltip

It is largely complete. Things to fix include:

• Redundant wording and incomplete sentences in the description.
• The keyboard section needs revisions to bring it inline with APG editorial requirements.
• The states and properties section needs revisions to bring it inline with APG editorial requirements.
• Remove external links from example section.
  page.

Open questions:

• Should there be any guidance about using tooltip verses title attribute.
• The introduction links to the non-modal dialog section. Should that instead be to the tooltip dialog pattern called for by issue Draft tooltip dialog design pattern #85?

[mcking65]

Fixed editorial issues in commit b1407a8.

[wendyabc]

Yes, please do include guidance on using tooltip vs title attribute.

[mcking65]

@wendyabc, do you have some specific issues in mind that such guidance should address?

[paulwaitehomeoffice]

This may already be in hand, but the current wording of the keyboard interactions reads as slightly ambiguous to me:

A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. It typically appears after a small delay and disappears when Escape is pressed or on mouse out.
...
If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur). If the tooltip is invoked with mouseIn, then it is dismissed with on mouseOut.

Should pressing Escape always dismiss the tooltip, or only dismiss the tooltip if it was invoked when the trigger element received focus?

[carmacleod]

Yes, please link to the tooltip dialog pattern rather than the non-modal dialog section.

[carmacleod]

Regarding tooltip vs title: at present, I am not aware of any way for a sighted keyboard-only user to see the content of the title attribute (unless they are using an AT).
So, one advantage of using a tooltip is that the tooltip can be displayed for keyboard users, either by:

• automatically opening the tooltip when the element receives focus, or
• providing a keyboard shortcut, such as F1 or Shift+F1, or maybe F2 to open the tooltip for the focused element

The advantage of automatically opening the tooltip when the element receives focus is that this makes the tooltip very discoverable for keyboard users, but the (big) disadvantage is that keyboard power users very quickly become tired of them, even when there is a delay.

The (big) advantage of providing a keyboard shortcut to open the tooltip is that users can choose when they want more information. The disadvantages are:

• discoverability of the keystroke that will open the tooltip (standardization would really help here, but this info can be provided along with other accessibility tips and settings for the site)
• the developer needs to provide a visual affordance that there is a tooltip available for an element (note that AT users would not need an affordance, because the tooltip pattern explicitly requires the use of aria-describedby, which would count as the affordance in this case)

[carmacleod]

The first sentence of the tooltip pattern is:
"A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it."
The previous comment discusses 2 ways that a tooltip can be displayed for keyboard users:

• automatically opening the tooltip when the element receives focus, or
• providing a keyboard shortcut, such as F1, Shift+F1, or F2, to open the tooltip for the focused element

So I think we should change that first sentence to something more like the following:
"A tooltip is a popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it, or when a focused element receives a specific keyboard shortcut to display the tooltip."

[ZoeBijl]

What exactly is the point of having esc close the tooltip if it appears on hover/focus? As it would close when the control that invoked it is no longer hovered or focused (as mentioned in the note under keyboard interaction).

Related thread on Twitter.

[carmacleod]

Regarding having ESC close the tooltip, if a tooltip is shown (and focused) when the user types a keyboard shortcut (such as F1, Shift+F1, or F2), then ESC can be used to hide it.

Alternatively, perhaps any Tooltip that is optionally shown/focused on a keyboard shortcut falls under the jurisdiction of the Tooltip dialog pattern (issue #85), even if it only contains text?

[jnurthen]

Having ESC close the tooltip allows you to close it if it is distracting. For example, if there were a really big tooltip attached to something which obscures some other information you may want to see when filling in a form field.

…

On Tue, 23 May 2017 at 07:53 Carolyn MacLeod ***@***.***> wrote: Regarding having ESC close the tooltip <#128 (comment)>, if a tooltip is shown (and focused) when the user types a keyboard shortcut (such as F1 or F2), then ESC can be used to hide it. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#128 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABpQP5PUcJCVRG41WS5jMhxaeQWzhMjkks5r8vLkgaJpZM4KYHKf> .

[carmacleod]

Having ESC close the tooltip allows you to close it if it is distracting.
For example, if there were a really big tooltip attached to something which
obscures some other information you may want to see when filling in a form
field.

Agreed that that would be a nice thing to have. Note that the ESC key would go to the trigger element in that case, and not the tooltip, because according to the spec, "Tooltip widgets do not receive focus."

[steverep]

The below note seems to violate a success criterion being proposed for WCAG 2.1:

If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur). If the tooltip is invoked with mouseIn, then it is dismissed with on mouseOut.

See w3c/wcag21#75. There are accessibility reasons for the tooltip to persist while the tooltip itself has mouse hover.

[guyhickling]

The disadvantages are: discoverability of the keystroke that will open the tooltip (standardization would really help here, but this info can be provided along with other accessibility tips and settings for the site)

The above would be true where an item of content must be clicked on by mouse users to reveal the tooltip text; here the keyboard user would need an F1 or similar shortcut as suggested.

But most tooltips I see involve a separate button beside the content, usually with an icon on them such as a ? character, or an I for information, or even the word Help. Depending on what interactivity the designers have chosen the keyboard user either focusses on it using the Tab key to reveal the tooltip, or they must press Enter or spacebar to reveal it. This kind of tooltip should be allowed for in this SC (I believe they can still be considered tooltips, as they perform the same function and behave the same way, they are just tooltips on the dedicated button instead of on the content itself).

These cases use the element (or they should though many developers use an instead, but that's another story). Whether or the keyboard interaction is defined in the HTML spec, and keyboard users know how to operate buttons and links (pressing Enter works for both) so there is no need to provide extra info for it.

[carmacleod]

Our use case is a code editor. Users can open a tooltip anywhere in the editor, to show the comment for a method or variable, the detailed text of a compiler error or warning, the details of a breakpoint for the current line, etc. Mouse users can see these tooltips by simply hovering over the function/variable name, error/warning indicator, or breakpoint annotation. Keyboard users need to navigate to the "trigger location" using the arrow keys, and then they can optionally open the tooltip by pressing F2.

Note that the editor itself is the "trigger element", but it has focus the whole time, so focusIn cannot trigger the tooltip(s). It is the caret location that determines which tooltip is shown. It does not make sense to open them automatically when the caret reaches the intended trigger location because that gets incredibly annoying.

If you are familiar at all with the Eclipse IDE, this is the way their code editor works. We used the same technique in our code editor because our Web IDE (Orion) was mostly written by Eclipse devs. :)

An additional "quirk" of this technique is that a mouse user can hover to open a tooltip, and then, if they want it to take focus for whatever reason (some of the tooltips have buttons or links in them, which can be activated with keyboard or mouse), they simply type F2 and we give the tooltip focus. Esc closes it.

One could argue that these are "dialog tooltips" and not "tooltips", or maybe they are a different beast altogether, but the typical mouse experience feels exactly like a tooltip, so we tried to keep the keyboard experience as close as possible.

I could imagine an map or some other complex visualization working in a similar manner - the map has focus, the keyboard user navigates with arrow keys, and any time they want more info on the current location, they type F2 to get a tooltip.

[Yaffle]

the title attributes sets the "aria-labelledby", not "aria-describedby", right?
So is there cases for tooltips when aria-labelledby should be used - like for a "toolbar button" (icon+tooltip) ?

[craigkovatch]

I would like to see guidance about whether elements with role=tooltip are intended to contain text-only content, i.e. functionally equivalent to the title attribute.

[carmacleod]

I would like to see guidance about whether elements with role=tooltip are intended to contain text-only content, i.e. functionally equivalent to the title attribute.

I believe the tooltip pattern is intended to contain text-only content,
and the tooltip dialog pattern is intended for tooltips with interactive children.

@mcking65 can correct me if I am wrong.
If this is correct, then yes, it should be explicitly stated in the pattern doc.

Please see #85 for discussion on the tooltip dialog pattern.

[craigkovatch]

I believe the tooltip pattern is intended to contain text-only content,
and the tooltip dialog pattern is intended for tooltips with interactive children.

Thanks @carmacleod! What about formatted text, e.g. bold or italics? Is the differentiating factor "interactivity", or is it closer to "anything that's not a plain string"?

[craigkovatch]

an anti-anti-anti-pattern

Wait @StommePoes are you saying that anti-patterns don’t cancel out??

Crap, now I have to redo everything! 🤣

[StommePoes]

Wait @StommePoes are you saying that anti-patterns don’t cancel out??

They do, which is why there's an uneven number in my post. An anti-anti-pattern restores balance in the universe. An anti-anti-anti-pattern creates a maze of twisty little passages into hell.

[accdc]

Hi,
To recap as we spoke of during the APG call, in order for a broader discussion of tooltip variations to be documented within the APG, we need to index the primary tooltip types and how they differ. Since I've already done the work in building these in practice, I'll break these out to illustrate the differences and associated caveats with each.

First, as I personally expect for these, all tooltips are never directly focusable, nor do they ever include any active elements. Defining this difference illustrates the difference between a tooltip and a non-modal dialog, both of which have very different requirements for accessibility.

In my experience, there are typically 3 primary tooltip category types, standard tooltips, dynamic error tooltips, and dynamic responsive tooltips. The sub-variations fit within each of these.

Standard Tooltips

Behaviors: Standard tooltips are always directly invoked on the focused triggering element, even if the mechanism for doing so may differ between implementations. Also, when the tooltip is set, it remains static and unchanging for as long as the associated tooltip is rendered, even if the tooltip is animated to appear or disappear. Pressing the Escape key on the triggering element will remove the visual tooltip. All tooltips in general can only be invoked from focusable active elements, and focus should never be forcibly moved away from the triggering element when the tooltip is rendered.

The simplest standard tooltip type consists of a focusable active element that references another element using aria-describedby, which causes the Description property to be set on the focused element in the accessibility tree. As an aside, the aria-description attribute can now be used to do the same thing in all mainstream browsers without having to reference an external element, even though this is technically an ARIA 1.3 addition. This capability is important in some circumstances. E.G. The use of aria-describedby can only reference elements that already exist within the DOM, and AT support degrades rapidly when aria-describedby is dynamically set on an element that already has focus, such as when a tooltip is dynamically created after a time delay such as 1.5 seconds after an element receives focus or is moused over. In contrast, aria-description can be set regardless if the tooltip is rendered in the DOM at the same time.

There are 3 different standard tooltip types demonstrated at: http://whatsock.com/Templates/Tooltips/Internal/

The first tooltip displays a tooltip only after the triggering element is explicitly activated by pressing Enter/Space or by clicking/double-tapping it. The focused element is a toggle, and will dismiss the tooltip if activated again. Pressing Escape will similarly dismiss the tooltip; so too will tabbing away from the triggering element. Mouse users can mouse into and out of the tooltip, or directly click or tap it to dismiss it on touch devices.

The second tooltip is triggered by an edit field, and will do so only when the field receives focus. The same pattern for dismissing the tooltip, however, is available by pressing Escape, tabbing away from the field, or mousing into and out of the tooltip or by clicking or tapping it.

The third tooltip is rendered when the triggering element receives focus or is moused over. In this case, since the tooltip element does not exist in the DOM to be referenced using aria-describedby, the aria-description attribute is set to explicitly set the Description property in the accessibility tree instead, regardless if the tooltip is visually rendered at the same time. It must be noted that aria-description is not supported in IE11, and never will be.

A variation of the above standard tooltip type can often be used to represent static inline form field errors after a form submission, where aria-describedby or aria-description is set on the form field in error before focus is set back to that element, thus causing it to be announced when the field receives focus.

Dynamic Error Tooltips

Behaviors: dynamic error tooltips are never directly invoked on the focused triggering element, but rather, only after focus moves away from the triggering element. Thus, aria-describedby and aria-description can never be relied upon for this purpose. When focus is set back to the form field where the dynamic error tooltip is displayed, the tooltip will automatically disappear to prevent obscuring surrounding content.

Example: http://whatsock.com/Templates/Tooltips/Error%20(Inline)/

In this case, since an explicit description cannot be set, a live region is used instead to announce the error tooltip content when focus moves away from the required form field. The simplest and most unobtrusive way of doing this is to use aria-live="polite", which will cause the error to be announced without interrupting speech and preventing the next field in the tab order from being announced when it receives focus.

At present, this works best in Firefox when using a screen reader like JAWS. Live region support in general is still buggy and not always announced as it should be in mainstream AT/browser combos such as JAWS in Chrome, which is disappointing.

Dynamic Responsive Tooltips

Behaviors: Dynamic responsive tooltips are always directly invoked on the focused triggering element, and change programmatically as the user interacts with the field.

Example: http://whatsock.com/Templates/Tooltips/Help%20(Responsive)/

Though it seems intuitive that aria-describedby or aria-description can be used to handle this, this is only partially true. On desktops and laptops where focus is set on the triggering element, dynamically updating either aria-describedby or aria-description will fire a description_change event in the browser, thus causing the newly referenced content to be announced when the Description property changes in the accessibility tree. However, this will only occur when the Description changes on the currently focused element. As a result, this will not work at all when using a mobile platform like iOS where the act of typing into a virtual keyboard causes focus to be present elsewhere while the Description changes. As a result, it is necessary in this case as well to rely on a live region such as aria-live="polite" to announce the newly rendered tooltip content when it appears, which is also subject to the same drawbacks as described with the dynamic error tooltips.

Hopefully this helps to clarify and break down the main differences a bit.

All the best,
Bryan

[sinabahram]

Thanks for this fantastic breakdown. Question, how do you reconcile pressing escape with the fact that screen readers such as Jaws and NVDA, within a forms/focus mode, use this to exit that mode? Does this not mean that an SR user cannot dismiss the tooltip without negatively impacting their form-filling experience? I'm less worried about blind SR users, as they have a rare, but not non-zero need (think demos), to dismiss tooltips, but what about sighted SR users that do have such a need or those using magnification with speech where the above concern still holds?

[accdc]

Unfortunately sighted screen reader users will experience the difference you mentioned, and I haven't found a graceful workaround for that. Basically there is a simple keydown event to detect when Escape is pressed, after which the tooltip is removed. However in the case of screen readers, the AT itself is hijacking the keypress in specific circumstances and does not pass the keystroke through to the focused control, which prevents it from doing what is expected. Some people have tried to overcome this by adding role=application around the control to force the user to stay put, but this is a very bad idea and should never be done for the purpose of hacking a screen reader that is hacking the page right back.

[smhigley]

Thanks @accdc for that writeup and the examples! I tried to condense those + some of my thoughts into a potential outline of examples for the tooltip design pattern. I'd be curious what you (and everyone else) think about it:

1. A section on "traditional" tooltips (i.e. tooltips that appear only on hover and focus)
   • Example 1: an icon button with a tooltip showing the text alternative
   • Example 2: a short text description on an input field
   • I think we should also include text here on the accessibility pitfalls of both those tooltips in addition to information on how to make them as accessible as they can be. That can lead into suggesting toggletips as alternatives in the next section (and maybe mention including a legend as an alternative for inaccessible icon tooltips)
2. A section on toggletips
   • Example: a button that opens and closes a toggletip with help text for a form field
   • Some info on why they're a good alternative to traditional tooltips
3. Toggletips, but they're actually non-modal dialogs with interactive content
   • Example 1: this is sometimes called a "teaching tip", essentially a non-modal dialog with more info on how to use an interface, usually with buttons and links inside it
   • Example 2: A toggle tip for a form field, but with a link inside it
   • This functionally isn't that different from a text-only toggletip, but I think it's worth specifically calling out the a11y considerations of putting interactive controls inside what people colloquially call "tooltips"

I didn't include the error tooltip or tooltip with dynamic content because while I think the work on notifications is really interesting, it doesn't seem relevant to the tooltip pattern. It seems like they'd fit better into a section on how to author notifications and live regions (which we should also add 😄). I also think they'd do better as inline text rather than tooltips -- the live region considerations would be the same, but then they don't have any of the UX problems introduced by tooltips.

One other thing is I think we should consider control as a dismiss key in addition to escape because tooltips show up within dialogs, non-modal popups, menu dropdowns, and even combobox dropdowns with depressing regularity. If escape is standardized as the one single dismiss key, it'll cause problems in all of those cases.

[smhigley]

Notes from the meeting on 8/17:

Example brainstorming:

• example of double-tooltip: info and error on the same input at the same time (had pushback on showing this as an example, question of whether it's actually a common enough pattern to warrant showing it + it has a lot of drawbacks)
• Show both an icon button toolbar w/ tooltips and a single icon tooltip
• form field tooltip
• toggletips and non-modal dialogs
• Need to make sure it's clarified that a toggletip is not a tooltip, and be very clear on which examples don't use the tooltip role

Guidance section:

General guidance section:

• clearly define traditional tooltip, and what that is vs. toggle-tips/dialogs
• a traditional tooltip supposed to replicate the host tooltip/title attribute
• that's why there's no interactive content or structured content in a tooltip
• segue to next section: if you need anything that couldn't be covered in a title attribute, you also shouldn't put it in a custom tooltip. You'd actually want toggletip/dialog

Behavior:

• dismiss on delay: stay away from auto-dismissal entirely -- because if APG shows it, people will complain that their tooltip fails WCAG. APG should not show WCAG-failing examples (Scott, Eric, Jerra all agree)
• dismiss on ctrl AND escape (optional) in our example, specify why escape has issues (e.g. in a modal)
• (OPTIONAL): delay to show (browsers do)
  • two examples, toolbar w/ bunch of icon buttons = delay, tooltip on form field = no delay
  • needs note that explains why optional, why one person might want a delay but another might not, but be internally consistent
• Touch:
  • apple has done some work on this, e.g. first tap shows tooltip, second performs action
  • apple again: title attribute shows on long press (don't think we can replicate this?)
  • should we actually do the one touch to show tooltip, second to perform action (straw poll: don't do this, seems counterintuitive)
  • Suggestion: show the tooltip on touchstart, dismiss on touchend
• Voice: doesn't work with this
• Need to check with reader view, HCM (e.g. does a tooltip get inserted into the text in reader mode? Does using HTML hidden fix it if it does?)
• Doesn't work on a static element either, need to specify that it's bad practice and why (keyboard triggering and screen reader support). Good place to note that one would need a toggle tip instead.

[DavidMacDonald]

I noticed that screen readers don't seem to announce the role tooltip on this type of example

<button ... aria-describedby="p1">...</button>
<div role="tooltip" id="p1"...>Lipsum...</div>

Or this

<button ... aria-labelledby="p1">foo</button>
<div role="tooltip" id="p1"...>Lipsum...</div>

Also our working example has aria-labelledby and in that case it overrides any text in the button so in that case either use aria-describedby or have 2 ids in the labelledby, the button self reference and the tooltip

<button ...  id="p1" aria-labelledby="p1 p2">foo</button>
<div role="tooltip" id="p2"...>Lipsum...</div>

[JAWS-test]

@DavidMacDonald

With which browser and screen reader does it not work? I have checked the examples with JAWS and NVDA and they work

[tychenjiajun]

If the related element is not visible, should we close the tooltip?

[mbgower]

@tychenjiajun this is a very long thread. Can you please cite the prior comment you are referring to, or provide some more context?

If the related element is not visible, should we close the tooltip?

[tychenjiajun]

@tychenjiajun this is a very long thread. Can you please cite the prior comment you are referring to, or provide some more context?

If the related element is not visible, should we close the tooltip?

Reakit Tooltip is a tooltip component that claims to follow this pattern. However, it has weird behaviour. When I tab on a reference to open the tooltip, then scroll the page's scrollbar using the mouse until the reference becomes invisible, the tooltip is still visible. Should scrolling dismiss the tooltip?

[mbgower]

@tychenjiajun said:

However, it was weird behaviour. When I tab on a reference to open the tooltip, then scroll the page's scrollbar using the mouse until the reference becomes invisible, the tooltip is still visible. Should scrolling dismiss the tooltip?

No, it should not be dismissed, and I wouldn't consider that weird. It seems to follow the guidance: you tabbed to it, so you have put focus on it, and scrolling the page is not removing focus from the reference.
If you had triggered the tip with the mouse, then scrolling away would move the pointer off the reference, which should cause it to go away. But once invoked by focus, it's going to stay there until focus is lost.

This Note might help:

Focus stays on the triggering element while the tooltip is displayed.
If the tooltip is invoked when the trigger element receives focus, then it is dismissed when it no longer has focus (onBlur). If the tooltip is invoked with mouseIn, then it is dismissed with on mouseOut.

[Gcamara14]

Any updates on this tooltip? This tickets been open for quite sometime.

https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/

[mbgower]

@tychenjiajun, I just had a look at the Reakit tooltip you have now linked to in your comment, instead of just reading the behaviour you described. I see what you're talking about. I think what's happening is that this tip's behaviour is colliding with a few other things on this page:

1. They have a floating banner which obscures content, however the tooltip seems to be on a layer above this banner, so while the trigger for the tooltip becomes hidden under the floating banner, the tooltip stays visible on top
2. They have some dynamic positioning of the tooltip, which responds to the viewport edge, and so moves the tooltip below the trigger as the trigger gets near the top of the page. It makes the tooltip reposition over top of the banner as a user scrolls

I think those are both problems with the banner implementation, not with the tooltip. I guess the one thing that could be investigated is if the styling that is putting the tooltip over other content could result in other page oddities with regard to the tooltip display. Worth Reakit testing.
I'm a little surprised to see the tooltip dynamically reposition based on other content. Some people may like that. Some may not. I would have thought it was stay stationary once appearing. But I don't think the reposition would be considered a failure of anything?

[clshortfuse]

Microsoft Windows closes tooltips with Ctrl not Escape. I have bigger writeup at #2538 specifically addressing this.

Key points are: "Escape" is irregular. We lack a general pop-up ARIA for "rich" popups. Tooltips should not be "rich".

[cseas]

We have a use-case where we want to show the tooltip for a few seconds on initial page load and automatically dismiss it. After that the tooltip goes to regular behaviour and only appears on hover. Is this usage against the tooltip design pattern UX?