Repository navigation
Refactor the ARIA structure of the flyout #9495
Description
The flyout's ARIA structure should be updated as follows:
- The flyout's role should become
menu - Labels should have their role set to
heading - Each set of items between a label should be wrapped in an element with role
group - All other flyout items should have their role set to
menuitem
Activity
BenHenning commentedon Dec 3, 2025
One open question I had is whether the readout will work correctly if there are no headings present, but looking into https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role I'm actually questioning the opposite: it doesn't seem standard to include headings within menus. It might be worth trying to find a standard HTML example of this that we can look at with a screen reader in order to see how it behaves in order to replicate it.
microbit-robert commentedon Dec 5, 2025
Chakra UI is good for accessible components and they have a menu example with groups and headings, but I must admit I've not tried to find other examples yet. It is also currently unclear to me whether groups of menuitems must have headings or not.
FYI, I very briefly tried switching the flyout to a
menufrom atreeand this seemed to break VoiceOver when navigating to the toolbox. I didn't get the bottom of what was happening, but presume the accessibility tree was broken by this change in some way.feat: Make `Flyout` an ARIA `list` (experimental) (#9528)
BenHenning commentedon Apr 14, 2026
I took a deeper look at the node tree from the Chakra UI example. It's interesting because they aren't actually following the spec per MDN (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role). My read of the spec is that
menus are supposed to have exactlygroupandmenuitemchildren. They do follow that except for headings which are just standarddivs with text (and are thus interpreted as static text in the node tree). I want to note these are not actual real headings in the ARIAheadingrole sense, and I'm not sure those would actually behave correctly.I'm not sure we actually want to follow this pattern. While
menuis nice, it also doesn't quite perfectly match what aFlyoutis. My understanding is thatmenus are supposed to specifically be pop-up UI experiences (https://www.w3.org/WAI/ARIA/apg/patterns/menubar/) which theFlyoutisn't quite. Now I'm not necessarily sure thatlistis any better but that actually does more correctly support headings as far as I can tell.We don't really get any particular benefits for
lists in terms of automatic modes, though, since we're overriding all screen reader interactions by using the root injection devapplicationrole.Do you have any thoughts on this @microbit-robert?
microbit-robert commentedon Apr 14, 2026
@BenHenning I don't currently have a good handle on this, and also don't know what the 'correct' solution is, perhaps there isn't one.
The magical combination would be a suitable role for the flyout and flyout items that would also, while having a screen reader running, naturally support the up/down arrows without having
role="application". This would allow screen reader key's such as 'h' to move to the next heading. I'm really not sure such a role exists though.I think the
listrole works reasonably well as is. Regardless, these are two key things we want to keep in terms of screen reader output:Things proven to be confusing:
I'm also not sure if grouping items with a heading improves anything in terms of screen reader support or just makes things more complicated.
BenHenning commentedon Apr 14, 2026
Got it, thanks @microbit-robert. At this stage it does seem better to avoid
menujust because it doesn't really fit what we ultimately want.The rest I definitely agree with. To some extent we're really just shoehorning in properties to try and get the behavior we want, so it might be a bit finicky (it seems completely broken for me in the current keyboard nav plugin demo deployment with ChromeVox, for example). I think we have a solid idea as to what we want the end behavior to be, but it does seem unclear exactly how to get there. It probably makes sense to continue with the list approach and try to tweak it to better fit the end experience that you describe here.