Clarify usage of aria-haspopup

[scottaohara]

Coming out of our discussion of #999

We should review aria-haspopup and determine if there should be stronger guidance about what the expectations are for when the attribute should be used, and what sort of variations in behavior should be expected when using the different allowed values.

For quick reference, the current values are:

• false (default)
• true and menu
• listbox
• tree
• grid
• dialog

Specifically regarding the dialog value, it was mentioned on the call that when this should be used is ambiguous right now.

As a quick sampling of how this particular value is presently communicated by screen readers when used on a button element:

Latest JAWS and NVDA both treat a button aria-haspopup=dialog as a menu button, and produce announcements as if the value were true or menu.

iOS VO announces "shows popup. double tap to activate a picker".

macOS VO announces it as a "popup button" similarly to a select element's announcement.

[scottaohara]

To help move discussion on this along I created a test page noting how VoiceOver, JAWS and NVDA expose (and by that I mean mostly don't) any of the specific pop-up values. In most cases, the aria-haspopup is indicated by changing the element to append the announcement "pop-up" or "menu" or "submenu".

Only with JAWS with Chrome and Firefox did the special designations get announced on links.

[jnurthen]

NVDA issue for aria-haspopup is nvaccess/nvda#8235

[carmacleod]

JAWS issue for aria-haspopup is FreedomScientific/standards-support#33

[scottaohara]

i'm going to move this to 1.3. I don't think there's time, nor urgency, to tackle this in 1.2.

[mfairchild365]

For whatever it is worth, the latest versions of VoiceOver for iOS and MacOS now fully support all values for aria-haspopup. Details and test results: https://a11ysupport.io/tests/tech__aria__aria_haspopup_attribute

[scottaohara]

that's great to hear. thanks @mfairchild365

[joanmarie]

Just out of curiosity, how important is it to explicitly announce the popup type? If a user is on something with a popup, and activates that popup and winds up in a grid, will the user be completely confused if the screen reader failed to notify them in advance that a grid would appear?

As a sighted user, I don't know in advance what is going to pop up when I activate something with a pop up. I just activate it and see what happens. If a grid appears as a result, my conclusion is that the grid appeared because it's the popup.

To me, tacking on the type seems like it might be unwanted chattiness.

If it's truly important, I can add announcement in Orca. But I was operating under the assumption that this information was mainly of use to the screen reader itself (e.g. an explanation regarding why a grid is claiming to be showing).

[joanmarie]

Related question: Combo boxes by default pop up a listbox. Is it considered a screen reader "failure" if it doesn't announce that a combo box opens a list box? Were I the user, my reaction to that announcement might be "of course it does. why are you telling me this?"

[mfairchild365]

That's a really good question. There are cases where I think it is important to explicitly announce the popup type. For example, many ARIA based <select> elements have a button with aria-haspopup='listbox'. The listbox itself is not displayed until after the button is activated. In these implementations, there is often a visual hint that the button opens a listbox such as a down arrow to the right of the button label. So, aria-haspopup='listbox' conveys that same visual information. The APG has an example of this in the Collapsible Dropdown Listbox Example.

It may be less important for other values, but I think there are situations where it is very important.

[carmacleod]

@joanmarie

Just out of curiosity, how important is it to explicitly announce the popup type?

As long as the screen reader doesn't say "menu button" when aria-haspopup="dialog". :)

[scottaohara]

It may be less important for other values...

and there in lies the source of this issue being created. :)

[joanmarie]

Ok, I just implemented support for it in Orca master: https://gitlab.gnome.org/GNOME/orca/commit/25c64254

Edit: because duh https://gitlab.gnome.org/GNOME/orca/commit/8368b43. Long day.

Many Orca users (at least those on the Orca mailing list) run Orca master in their production environments (bless their adventurous hearts). Let's see what they say (if anything).

[carmacleod]

@mfairchild365

there is often a visual hint

Good point. In the case of the APG Collapsible Dropdown Listbox Example, NVDA (for example) says "menu button", which is almost correct, and even has similar keyboard interaction, but doesn't tell the user that they will be "selecting the button's value from a list". (which is kind of an important thing to know, and makes me wonder whether that example should be a combobox instead :) ).

Edit: I suppose if NVDA had instead said "Neptunium popup list button" or "Neptunium button, opens listbox", then that would be an indication that the chosen list item would end up as the button's text.

[carmacleod]

Ok, I just implemented support for it in Orca master

Nice! Would love to know what the Orca users say. Please do let us know.

[joanmarie]

That's a really good question. There are cases where I think it is important to explicitly announce the popup type. For example, many ARIA based <select> elements have a button with aria-haspopup='listbox'. The listbox itself is not displayed until after the button is activated. In these implementations, there is often a visual hint that the button opens a listbox such as a down arrow to the right of the button label. So, aria-haspopup='listbox' conveys that same visual information. The APG has an example of this in the Collapsible Dropdown Listbox Example.

When an Orca user (using the stable version) encounters that button, Orca says the following:

Choose an element: Neptunium push button.

When you hear that you know what you need to do conceptually, namely choose an element. In addition, you know what the current choice is, namely Neptunium. If Neptunium ain't your element, what do you do? It's clear that you push the button.

When the same Orca user presses the button, the listbox appears and Orca says the following:

Expanded
Choose an element: List with 26 items
✓ Neptunium.

Depending on user settings, Orca may also tack on:

1 of 26.

That should be enough for the user to know what to do in the list.

I will grant you that failure to present an equivalent of the downward pointing triangle means there is a moment when sighted users have more info than blind users. But I don't personally believe that one moment is significant: You have to choose an element, you're on the thing which lets you choose elements, you activate it and the element-choosing-widget is described so you can choose the element.

But now, Orca master tacks on:

opens listbox

That makes presentation longer. Speech output is already slower than visual output. And as I describe above, I'm not convinced that longer presentation buys the user anything. 🤷‍♀️

[mfairchild365]

Thank you, @joanmarie - that is insightful and you bring up many good points. I agree that in the specific APG example, there is enough information for a user to infer that this button probably opens a list box or some other thing that lets me change the value. I'm less willing to say that holds true for other situations where the name and/or value might not be as clear. Additionally, explicitly conveying the fact that this button opens a listbox might lessen the cognitive load required for someone to understand what they need to do to adjust the value. That's just a hunch, and I don't know that to be true.

I love that you made the change in an effort to collect feedback from end-users. I'm looking forward to hearing the results of that. IMO, that sort of research is one of the best ways to drive decisions like this.

But I was operating under the assumption that this information was mainly of use to the screen reader itself (e.g. an explanation regarding why a grid is claiming to be showing).

I'd like to better understand this statement. How would this information affect the internals of how a screen reader works? If an author did not provide this attribute, how might that impact the experience of the end-user if it is just used for the screen reader itself?

[scottaohara]

How would this information affect the internals of how a screen reader works? If an author did not provide this attribute, how might that impact the experience of the end-user if it is just used for the screen reader itself?

you mean the attribute, or specific token values of the attribute?

[mfairchild365]

Good question. Both.

[brennanyoung]

I suggest that the problem is not that NVDA fails to announce the other popup types, but that it specifically mentions one of them (arbitrarily chosen by tech history), but not the others.

If the rationale for not announcing the popup role is to reduce chattiness, why does NVDA announce "menu" or "submenu" (which isn't even an aria role) in the first place? Isn't that 'chattiness' too?

Either announce all the enumerated popup roles mentioned in the spec, or announce none at all, and make a briefer, more generic announcement about 'a' popup.

No matter what, a dialog is very much not a menu. Can't even get around this mislabelling with aria-roledescription in this case.

[joanmarie]

Nice! Would love to know what the Orca users say. Please do let us know.

Not a peep. So they're not bothered by it at least. Though I don't know how much they're encountering it in the wild.

[sinabahram]

I think it is critical to talk about behavior in addition to announcement. Please note that aria-haspopup="dialog" results in forms mode being enabled upon invocation in Jaws, and I believe insert mode in NVDA as well. This is highly problematic because the resulting modal dialog, let's say, is then not navigable as a document, independent of its role. This is something that comes up quite a bit on websites we work with developers on where they feel they are doing the right thing, and we tell them, don't at all implement aria-haspopup="dialog" because you will drastically degrade the experience for most screen reader users.

Regarding announcement, it is a good idea to give a priori information to the user when possible, I feel, because it helps set expectations. The metric I always use here is that for an eyes-free user, the cost of undo is almost always higher, often times much higher, than for a mouse or otherwise sighted user (just choosing these two groups for argument, obviously there are many more). Therefore, a minor annoyance can be dismissed with a flick of a wrist, but may take tens of seconds or minutes for a screen reader user to achieve the same result.

As a result, this heads up, I feel, is both useful and honestly necessary. Note that native platforms sometimes have paradigms for this, such as the '...' indicating a new window in MS Windows buttons.

Also, I just wish to say major props to Joanie for implementing this in Orca. Thank you for doing so.

[JAWS-test]

Please note that aria-haspopup="dialog" results in forms mode being enabled upon invocation in Jaws, and I believe insert mode in NVDA as well.

I have tested this in Chrome and Firefox, with JAWS 2019, JAWS 2020, and NVDA 2019.2.1 Neither for links nor for buttons did using aria-haspopup=dialog lead to switching to forms mode. Nor did the use of role=dialog switch to forms mode. I could read at any time with the virtual cursor (i.e. with the arrow keys).

@sinabahram: Do you have a link to the page where the problem occurred? I suspect that the cause for switching to forms mode was different from having aria-haspopup=dialog

[sinabahram]

RE forms/insert mode with aria-haspopup, can you please provide a test page, so I can compare results over here? We’re also going to code up some samples over here to make sure we can reproduce the behavior reliably, and I’ll share those as well.

[JAWS-test]

@sinabahram : this is my test page

[sinabahram]

Thanks for the test page. I just replicated the behavior with Jaws and Chrome, latest versions. I hit that button once, and it turned on forms mode, then turned it off, and then focussed the heading. I then closed the dialog by hitting yes or no, and I then just reproduced the exact same actions; however, this time, the forms mode didn’t toggle off.

[JAWS-test]

This is strange, I have no change to forms mode (JAWS 2020, Chrome 79).

[scottaohara]

next steps, @mcking65 and I need to work on a suggested PR.

another issue needs to be created (by me) regarding needing to inform users that a "popup" will have light dismiss behavior.

[guyhickling]

and I need to work on a suggested PR

So have you decided what the change will be? What will the PR advise and contain?

[jnurthen]

@guyhickling you can read the discussion at https://www.w3.org/2022/02/03-aria-minutes.html#t07

[masi]

Those minutes are incredibly hard to read. Only thing I could make out that there is no consenus at all.

Issues are IIUC mapping to the accessibility API of the OS, backwards compatibility with the spec, add properties or roles to a new version of the spec, implementation problems of current screen readers, lack of definition on what a pop-up actually is * and if non-sighted users need additional information.

• I assume that even if ARIA would define pop-up the definition will not match the average developers notion of a pop-up. I for example don't use the word drop-downs of a html select element.

[scottaohara]

I used the term 'suggested' purposefully when describing the todo to create the PR.

the point of working on a suggested PR is to help get consensus. Matt and I have ideas of where this should go, but they're not 100% aligned. We're going to work together to align them as best we can and then make the suggestion so that we have something concrete to talk about with the group. otherwise, we may all just continue to circle around the solution.

[masi]

Matt and I have ideas of where this should go, but they're not 100% aligned. We're going to work together to align them as best we can and then make the suggestion so that we have something concrete to talk about with the group. otherwise, we may all just continue to circle around the solution.

Thank you for going into all that troubles.

[daemoncron]

Just chiming in here, in 2022, this attribute has been around for a while, and still every time we see a screen reader user encountering aria-haspopup="dialog" in a user test, they are confused by it - generally thinking it is a menu (even when "dialog" is announced) because of the history of "popup" being a menu.

I think I'm going to advise we move away from using this on buttons that launch modals in favor of screen reader only text or aria-labels (kind of like "(opens in new window)" we could just use "(launches modal dialog)"), unless there's a better idea out there.

[sidnc86]

For ages, as a screen reader user on Windows, a major queue of notifying aria-haspopup="dialog" has been use of ellipsis. For example, in MS Word, if one had to bring up a paragraph dialog, the option would show up as "Paragraph...".
With Punctuation Level setting of most screen reader being set to either "some" or "most" by default, many screen reader users won't fiddle with these settings unless they are advanced users. The reason I bring up Punctuation Level setting is because the ellipsis indication is translated into "," like pause. Does the pause really help? Whether helpful or not is going to be quite subjective. But I thought to put the ellipsis usage in context because although not through direct roles, there has been ways to communicate that something pops up a dialog even at that non-web user interface.
As programmer, I thought aria-haspopup="dialog" was intended to add this ellipsis value to screen reader user's life. It is sad that screen reader vendors haven't yet implemented aria-haspopup="dialog".
I am not a big fan of using sr-only off-screen text to convey role, property or state information, Usage of such sr-only elements should be confined to giving out screen reader specific instructions.

[giacomo-petri]

Hello everyone,

thank you for raising this topic. It is an interesting one with a lot of comments and a very long discussion (I would have noticed it before).
After lot of years discussing the aria-haspopup topic with my team, I'm still struggling with it.

As always there are a lot of insightful hints, comments and thoughts.

---

From @sinabahram:

Regarding announcement, it is a good idea to give a priori information to the user when possible, I feel, because it helps set expectations. The metric I always use here is that for an eyes-free user, the cost of undo is almost always higher, often times much higher, than for a mouse or otherwise sighted user (just choosing these two groups for argument, obviously there are many more).

+1, I totally agree with this.

---

From @mcking65

We added the new haspopup tokens for the combobox role in ARIA 1.1 because there was some concern that screen readers need to know that the combobox would open something other than a listbox. I don't recall the origin of the concern. I have no recollection of how much anyone, including me, questioned it. We may be able to find more information in meeting minutes from 2016 or so. Regardless, I don't think whatever concerns were expressed at that time have been manifest in practice. So, I don't think screen readers need an attribute that tells them what kind of popup a combobox will open.

This is good to know but at the same time, in my opinion, it's not intuitive from specs. The "dialog" value seemed a bit off-topic considering the entire list of values and that's also why I've always thought about it as a useful hint to inform AT (screen reader) users about something (dialog) that will be visually displayed on screen after interacting with the element. In my mind, this interpretation was also supported by the list of "Used in Roles", which contains for example the link role (which usually is not used to display "menu, listbox, tree or grid" elements). That said, with the combobox information and assumption, the list of values makes more sense.

---

From JAWS-test

I have never understood why aria-haspopup can have different values. While sometimes there is a visual indication that something is opened by an element, I don't know any example where it is visually recognizable in advance if a listbox, tree, grid, menu or dialog is opened. So why does this information need to be perceptible in advance with AT and not visually?

And answer from guyhickling

a) It lets them know that in order to get back to where they were they have to do something (either look round for a Close button, or press Esc). This is quite different from drop-down content (e.g. accordion style drop downs), where you don't leave the page and you'll eventually get back to the rest of the page content if you just go on navigating long enough.

b) Telling users in advance lets them know what should have happened, in the event that it does not. The greatest problem with dialogs is that most developers do not know how to make them accessible.

As also stated previously by @sinabahram, in my opinion this is a key point. Different experience requires different cues. I'll expand this in my final thoughts.

---

From @zelliott

I'm curious what the a11y experts on this thread recommend developers do for now for controls that open dialogs. Should we add aria-haspopup="dialog" and live with the poor screen reader support? Should we add aria-haspopup"true"? Should we append some informative string "opens pop up dialog" to the control's label or description?

That's a very good question.
If the intent was to use the aria-haspopup attribute in combination with the combobox role I would say that, even if it's not properly supported by AT (only VO is properly informing users about correct value) in terms of user experience it might still work.
But considering that the aria-haspopup can be used also with other roles and, per my initial assumption, that it could be used as a hint useful to inform users about something (dialog) that is visually displayed on screen, with the current AT support (which didn't change during the past years) it can confuse users.
Do we have a final answer for this?

---

From @scottaohara

Discussion largely circled around a proposal to simplify aria-haspopup back to being an attribute specifically to be used for creating menu buttons, or to indicate that roles that would continue to allow the attribute (if any?) would allow for opening a menu.

If this proposal were to be accepted, aria-haspopup would be revised to have values of:
true, menu and false. menu remaining a valid value as its a synonym for true in this context.

for the remaining deprecated values, they would instead map to 'false. The use of aria-haspopup would no longer be required for roles that presently require them (e.g.,combobox`).

This might be an interesting proposal, but what the disability community - especially VO users which might be more familiar with something that currently works - thinks about it? Do they feel comfortable from no longer receiving hints about buttons that trigger dialogs? Are them somehow impacted from removing this support?

---

From @mitchellevan

As a sighted web developer, I used to have high hopes that aria-haspopup would gain support and express useful information about the most common patterns of dynamic content. Banner navigation fly-outs and toggle tips typically provide contextual visual cues that they will display content within the page, and the visual cues help set users' expectations for distinct interaction patterns. Controls which trigger a modal dialog usually do not convey that fact visually before a user activates them, but nevertheless I wanted to give screen reader users a heads-up about a potentially disorienting dialog.

+1, I think this is what AT users expect.

---

From @scottaohara

There are plenty of instances of content that 'pops up' that don't neatly fit into a dialog (modal or modeless) because, like a popup menu or listbox, when someone tabs away from the container the popup dismisses.

tbh, i'm far less concerned with whether aria-haspopup is used to convey that a user is going to interact with such UI, as much as I think it's worth exposing the fact that the content which has popped up has this type of behavior.

As you said, excluding combobox elements, there are still many instances of content that pops up; fly-outs, dialogs (modal and non-modal), tooltips (meant as generic element that appears on focus or over - sometime might be just a description but some other might contain operable controls or multiple details, e.g. password requirements), just to name a few.
And many times the aria-expanded attribute is not enough to convey what will happen (as @stes-acc mentioned, the aria-expanded is a state attribute, whereas aria-has-popup isn't).

That said, I'm not convinced that aria-haspopup="dialog" implicitly means that tabbing away from the component results in dismissing the popup. In the document there is no definition of "popup"; if this is the intent might be worth adding it.

Per aria-haspopup property definition

Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.

A popup element usually appears as a block of content that is on top of other content. Authors MUST ensure that the role of the element that serves as the container for the popup content is menu, listbox, tree, grid, or dialog, and that the value of aria-haspopup matches the role of the popup container.

Based on that, it might be used on all scenarios I've listed (fly-outs, modal and non-modal dialogs, etc.), which might not be dismissed automatically after tabbing away.

---

From @daemoncron

Just chiming in here, in 2022, this attribute has been around for a while, and still every time we see a screen reader user encountering aria-haspopup="dialog" in a user test, they are confused by it - generally thinking it is a menu (even when "dialog" is announced) because of the history of "popup" being a menu.

This is interesting; I understand and agree with that if using JAWS or NVDA. That said I experienced the opposite with real VO user testing activities.

---

My final thoughts:
I've always approached accessibility assuming that all users with different abilities must all be able to accomplish their task, but the experience, the "perceived journey", the modalities of interaction, the timing spent, etc., might be different. A website is compliant with WCAG when users are able to perform website tasks; a website is usable/accessible when users are satisfied about their navigation (and the efficiency of their navigation).
To better clarify my point and taking this topic as example, even if there is no visual indicator that an element will trigger the presentation of a dialog (dialog intended as modal dialog, that prevents users navigating outside also with the tab key), for screen reader users might be easier if they are able to predict what will happen interacting with the element; for example just being aware that pressing the escape key they will be able to dismiss it and return to the previous content is a good hint (they may try to use the back browser functionality instead). Also a low vision user (e.g. tunnel vision) that is helped by a screen reader might benefit about the announcement of the popup, if the popup is not presented next to the button that triggered it, knowing they might need to search for it around the page. Of course a sighted user, after interacting with the popup-button, is immediately able to recognise the widget, is able to see the "inert" background page with probably an opacity overlay between the background page and the modal, etc.
Experiences are different, perceptions are different, but allowing screen reader users predicting the dialog behaviour might be something that can be compared to the immediate feedback perceivable visually by a sighted user.

Similarly, when a link is opening a new window (target="_blank"), it's recommended to inform AT users about that (even if there are no visual cue), as for a blind user it might require more time to understand what happened and to return to the previous page (a bit off topic but I still don't understand why there is no way to map the target attribute to make AT announcing this detail). Is it not similar to a button element that opens a dialog? Maybe less intrusive but still something not immediate.

Consequently, I'm not sure that providing an AT hint only when it's visually available is fair enough, and I don't think that moving back to just three values ("true", "menu", "false") is ok, unless there is another way to convey that detail.

[spectranaut]

here are some comments from scott: https://gist.github.com/scottaohara/7ef3f2882c911824ac2da35294f6beb9

[cletusw]

Haven't tested personally, but it looks like latest JAWS (FreedomScientific/standards-support#33) and NVDA (nvaccess/nvda#14709 ) have fixed this now.

Table (not updated for NVDA yet, maybe it hasn't shipped a version with the fix): https://html5accessibility.com/stuff/2023/06/20/aria-haspopup-less-is-more/

[jnurthen]

Has this been resolved or is this still an issue? This issue is really long - if something still needs to be done could someone please create a PR for what needs to be done to resolve.

[jnurthen]

Based on https://html5accessibility.com/stuff/2023/06/20/aria-haspopup-less-is-more/ can we now close this?

[mitchellevan]

Can we now close this?

Yes.

@joanmarie

Just out of curiosity, how important is it to explicitly announce the popup type?

As long as the screen reader doesn't say "menu button" when aria-haspopup="dialog". :)

Because I agree with the above, and because this minimum support or better is now in latest versions of screen readers with widespread use, I say this issue should be closed without a change in ARIA.

A content creator might consider it important to support older screen reader versions, and therefore continue avoiding the newer values such as aria-haspopup="dialog". But it's safe to say back-compatibility concerns for aria-haspopup are now in the same range as for other ARIA features.

[scottaohara]

i think for now this can be closed. still things to consider with the actual practicality of this attribute... but those can be new issues.

[LaurenceRLewis]

I have always thought the following part of the spec confusing,

"Authors MUST ensure the popup element associated with a combobox has a role of listbox, tree, grid, or dialog."

because authors MUST is followed by;

"Elements with the role combobox have an implicit aria-haspopup value of listbox. If the combobox popup element has a role other than listbox, authors MUST specify a value for aria-haspopup that corresponds to the role of its popup."

These two paragraphs should be rewritten as;

"Elements with the role combobox have an implicit aria-haspopup value of listbox. If the combobox popup element has a role other than listbox, authors MUST specify a value, tree, grid, or dialog, for aria-haspopup that corresponds to the role of its popup."

Which brings me to wonder how relegating aria-haspopup to true/menu only will affect role combobox.

[mitchellevan]

I have always thought the following part of the spec confusing,

"Authors MUST ensure the popup element associated with a combobox has a role of listbox, tree, grid, or dialog."

because authors MUST is followed by;

"Elements with the role combobox have an implicit aria-haspopup value of listbox. If the combobox popup element has a role other than listbox, authors MUST specify a value for aria-haspopup that corresponds to the role of its popup."

This spec language is technically accurate as-is, because "implicit" does not mean informally implied or hinted at. It means the property has a specific value, programmatically determined from the element's role, as described in Implicit Value for Role.

Is it as clear as it could be? Maybe not... So I'd suggest requesting that clarification as a new issue, or go straight to a PR. This should be separate from #1024, so #1024 can be finally closed.

Which brings me to wonder how relegating aria-haspopup to true/menu only will affect role combobox.

I don't foresee that happening. Such a change in spec was being considered in past years, when some major screen readers were either not announcing information for non-listbox values of aria-haspopup or were announcing information inconsistent with the value. However, now that major screen readers are announcing information consistent with the existing spec, there is no longer a need for such a change in spec, and #1024 should be closed without a change.

[scottaohara]

this issue is closed.