[Spec] Remove TabIndex and IsTabStop properties

[rachelkang]

Remove TabIndex and IsTabStop properties

The TabIndex and IsTabStop properties, as implemented in Xamarin.Forms, were inspired by the native Windows APIs of the same name for keyboard accessibility. As for IsTabStop, it in unclear if it was ever even meant to be surfaced externally as a public API. In any case, neither property is native to mobile platforms, and neither was meant to natively affect screen reader navigation beyond keyboard accessibility.

According to API docs:

Controlling the tab sequence with a combination of IsTabStop and TabIndex rather than using the default tab sequence is sometimes necessary in order to tune the keyboard accessibility of your UI.

However, accessibility experts discourage these properties from being used on the native Windows platform. A lack of comprehensive understanding in the past led to the misimplementation and misusage of these properties, as further elaborated below. Therefore, TabIndex and IsTabStop will officially be removed in .NET MAUI and docs will be updated to reflect the best behavior.

Our initial understanding of the TabIndex and IsTabStop properties, as implemented in Xamarin.Forms, was that these properties would help developers to set the accessibility ordering - both (1) the order in which the keyboard "tab" button would navigate the elements and (2) the order in which the screen reader would read the elements aloud when touch-navigated. In manipulating the accessibility ordering even just a bit, the ordering of an entire view would be rearchitected, causing complicated calculations and buggy behavior. As a result, we saw that the few developers who were even using these properties were usually using them only to circumvent other accessibility bugs. Our developer community experienced the best results when advised not to use these properties altogether.

Windows story

TabIndex

General guidance around the TabIndex property suggests that the intended behavior for this native API was never clear, and that it goes beyond our initial thinking as captured in the API docs. Further research and discussions with internal accessibility experts lead us to conclude that TabIndex should be avoided wherever possible (and in most if all not cases, it is possible) as there are better ways of improving accessible content ordering.

Online guidance (i.e. https://dequeuniversity.com/checklists/web/reading-focus-order, https://accessibility.huit.harvard.edu/technique-focus-order-and-tabindex) also suggests that positive values of TabIndex should be avoided, and only zero and negative values should be used, for reasons unrelated to accessible content ordering.

IsTabStop

Same as above. See Windows docs for more.

Mobile story

As aforementioned, neither TabIndex nor IsTabStop are native to mobile platforms. However, there do exist Android and iOS equivalents that are more suited for the mobile platforms. With this in mind, we have the SemanticOrderView API in the Xamarin Community Toolkit that is a more platform congruent option, and with which customers have already had better success with. However, we will not yet be introducing such APIs in .NET MAUI.

Future guidance

Accessible design and mindful programmatic order remain the best combination when approaching accessible ordering.

For example, the use case in current Xamarin.Forms documentation is flawed. It suggests using TabIndex as a valid way to force the current design to be more accessible. However, the design itself was not the most accessible to begin with. In English, reading order is left-to-right, top-to-bottom so the names in the grid itself should've been rearranged themselves, improving the general content ordering and thereby fixing the accessible ordering more naturally and appropriately.

If there are any compelling use cases I may be unaware of or any further information I may be missing, please do share! In the meantime, SemanticOrderView in the Xamarin Community Toolkit remains a better alternative to TabIndex, although it is still discouraged from general usage.

[aledpardo]

Press F

[chadbr]

I’m a little confused. I see lots of reasons why it’s bad but no alternative for achieving the functionality when it’s needed in an application?

Thanks, Chad

[rachelkang]

Hi, @chadbr (and anyone else seeing this!) - if you're willing to share, I'm curious about what is your use case for which you may have used TabIndex in the past? I'd love to better understand if I'm missing something.

For the cases in which TabIndex was used to workaround accessibility bugs in the past, we will work to address those bugs head-on. And for cases in which TabIndex was used for accessible ordering, we've learned that altering design order and programmatic order (as opposed to tweaking accessible order with separate APIs) are often the best way forward - in cases where this is simply not enough on mobile, the SemanticOrderView API in the Xamarin Community Toolkit is an awesome alternative that is already available for use!

[llevera]

My view is that this is a good change, despite the obvious effects on backwards compatibility.

As described, order is usually best left to the OS on the basis of well arranged screen elements. Then, currently for cases where this order suits being influenced, the SemanticOrderView is currently the best option. I expect an API like this will also emerge in Maui itself, but in a later version based on this clearer platform

[chadbr]

fwiw, I've used these attributes since VB 3.0 (and probably before that?). And I don't think they had anything to do with accessibility back in the 90's. (I'm feeling very "back in my day" about this commentary now...)

A couple of common use cases:

• TabIndex - It is pretty common to want to enter data in a vertical pattern when you have multiple "columns" of controls -- instead of hopping from column to column (like pressing enter in excel vs tab). TabIndex allows you to control this... I've even seen it configurable in some applications (i.e. use can switch modes) and the TabIndex's are shuffled at runtime.
• TabStop - This one is pretty simple -- if you're using an input control in a read-only manner - removing TabStop makes it so tabbing doesn't stop on the control. I've seen it used to skip read-only controls, etc.

I'm completely ignorant of the underlying implementation details -- and the properties seem pretty useless on mobile platforms... but if you're doing hardcore data entry, it seems like you'd need this kind of control over the tabbing patterns on forms. If there's another alternative for achieving the same effect - that's fine.

That being said - the finer points of optimizing for rapid data entry seem to be getting dropped in most platforms these days - so maybe slow and irritating is fine now?

Thanks, Chad