Documenting tabindex='0' to help trap focus

[markscripter]

While working on making my own implementation of a dialog/modal accessible, I came across something that I think would help others if it was documented.

In this example, https://react-bootstrap.github.io/components.html#modals, when a user tabs outside of the modal, the focus goes to the tab bar, bookmark bar, etc. When the user's focus returns to the window's content, the focus is sent back to the modal as expected.

While looking at the example here, https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html, it does not do this. Looking into the code more, I found that this is because two divs are injected, one before and one after the dialogs content both containing tabindex='0'. This helps trap the focus and return it to the dialog's content.

aria-practices/examples/dialog-modal/js/dialog.js

Lines 161 to 165 in 47a3d81

	this.preNode.tabIndex = 0;
	var postDiv = document.createElement('div');
	this.postNode = this.dialogNode.parentNode.insertBefore(postDiv,
	this.dialogNode.nextSibling);
	this.postNode.tabIndex = 0;

I'm wondering if this is the expected behavior and if it is, can the documentation on the page be updated to include this?

Sorry if this has already been discussed before, I wasn't able to find an answer to it.

[mcking65]

@markscripter commented:

In this example,
https://react-bootstrap.github.io/components.html#modals,
when a user tabs outside of the modal, the focus goes to the tab bar, bookmark bar, etc. When the user's focus returns to the window's content, the focus is sent back to the modal as expected.

That behavior where tab can move focus outside of a dialog is problematic, especially if the dialog is modal.

While looking at the example here,
https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html,
it does not do this. Looking into the code more, I found that this is because two divs are injected, one before and one after the dialogs content both containing tabindex='0'. This helps trap the focus and return it to the dialog's content.

Correct; that is intentional. Trapping the focus like that is a primary feature of the example.

I'm wondering if this is the expected behavior and if it is, can the documentation on the page be updated to include this?

Yes, this is the expected behavior. It is reflected in the documentation in a couple of places.

First, in the dialog design pattern, it says:

Like non-modal dialogs, modal dialogs contain their tab sequence. That is, Tab and Shift + Tab do not move focus outside the dialog. However, unlike most non-modal dialogs, modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog.

Then, in the table of key commands it describes the behavior of Tab and Shift+Tab:

Tab

• Moves focus to next focusable element inside the dialog.
• When focus is on the last focusable element in the dialog, moves focus to the first focusable element in the dialog.

Shift + Tab

• Moves focus to previous focusable element inside the dialog.
• When focus is on the first focusable element in the dialog, moves focus to the last focusable element in the dialog.

Is this the type of documentation you are asking about?

The text of the example page and design patterns do not describe the JavaScript methods used to achieve the behaviors that are specified and demonstrated; the guide is focused on the WAI-ARIA implementation and associated UI behaviors. For engineers, the JavaScript itself is part of the guide, and we assume that people will read it.

[markscripter]

That behavior where tab can move focus outside of a dialog is problematic, especially if the dialog is modal.

@mcking65 could you go into more detail about the problems this creates? A few developers on my team and myself assumed this would be hijacking how tabbing works once you've reached the end of the document. Granted, it may not really be the end of the document but since nothing outside of the dialog can receive focus, it kind of mimics that behavior.

I guess the detail that get's implied is that while the dialog is open, tabbing outside of the current document's window is removed.

[mcking65]

markscripter commented:

That behavior where tab can move focus outside of a dialog is problematic, especially if the dialog is modal.

could you go into more detail about the problems this creates? A few developers on my team and myself assumed this would be hijacking how tabbing works once you've reached the end of the document. Granted, it may not really be the end of the document but since nothing outside of the dialog can receive focus, it kind of mimics that behavior.

Yes, it is indeed doing that.

Modal dialogs are an important tool for helping users focus on a particular task or message.
For screen reader and screen magnifier users in particular, it can be disorienting and potentially confusing when focus jumps way outside the dialog, to a far away and unrelated set of components in the browser's chrome.
A mag user will not likely even be able to see the dialog while the focus is in the chrome.
During that trip outside the dialog, which is quite long in most cases, it is very easy for users, especially users who are not fully aware of the browser's chrome, to accidentally or unknowingly go down a path that does not lead back to the dialog.

It is common for screen reader users to explore dialogs by tabbing.
While I don't have hard data on this, I believe they are more likely to explore a dialog by tabbing than explore a web page by tabbing.
At least that is true for me and a good portion of the screen reader users I have worked with over the years.
I believe it is a usage pattern that has it roots in desktop GUIs.
One reason is that the shorter and contained tab ring of a dialog is efficient where as the tab ring of a web page is long, clumsy, and a sort of last resort method of exploration.

I guess the detail that get's implied is that while the dialog is open, tabbing outside of the current document's window is removed.

Yes, I could agree with that ... it is an implied detail. Do you think it would be helpful to make that more explicit then?

[markscripter]

@mcking65 Thank you for your thorough and detailed explanation to the problems. That answered my questions around the implementation details.

Do you think it would be helpful to make that more explicit then?

I think it may help others in their own implementations as I've seen several that do not trap it like the example provided in this repository.

Thanks for your help!