SelectPanel

Accessibility and usability expectations

The button that opens the SelectPanel contains text that indicates the currently selected option(s). This current value, together with the actual label for the SelectPanel, must be part of the button's accessible name and conveyed to screen reader users when the button is focused.

The button, when activated, opens the SelectPanel itself as a dialog. This functionality must be programmatically exposed to screen readers.

Once the dialog is open, focus is moved to the dialog, and maintained inside the dialog until the user explicitly dismisses it. In the case of single-value SelectPanel, the dialog can be closed after the option has been selected.

The dialog can be dismissed/closed by the user, even without making any changes/selections. Keyboard users can dismiss it using the Esc key, while mouse/touch users can dismiss it by clicking/tapping outside of the open dialog. Once the dialog is closed, focus returns to the button that triggered the dialog.

When the SelectPanel dialog is opened, the title of the dialog, as well as any optional description contained in the dialog header, is announced by screen readers.

When the dialog is opened, focus is moved automatically to the filter input. However, the "virtual" focus for the SelectPanel is also placed on the first option in the selection list. Both of these aspects - where the "real" focus is, as well as the first option - as well as the number of visible options is exposed to screen reader users.

When entering a value in the filter field, the list of options is dynamically updated. Once the list has been updated, the number of options available is exposed to screen reader users.

Using the cursor keys, keyboard users can move the "virtual" focus through the list of options. For screen reader users, the currently highlighted option is announced, together with an indication of whether or not the option is currently selected or not.

When options are grouped into sections with separate headings, screen readers announce when the user has moved their "virtual" focus into a new group, and what that group's heading/label is.

If the SelectPanel has additional controls in the footer, after the list (such as an "Edit" button), keyboard users can reach these controls by Tabbing to them inside the dialog.

Both the input field, and the currently highlighted option that has the "virtual" focus, must have a clear focus indicator. The same applies to any additional controls in the panel's footer.

Built-in accessibility features

Currently, when the button to open the SelectPanel has a visible external label, the content of the label overrides the content of the button, and does not announce the visible value of the button.

The button includes aria-haspopup="dialog" - its purpose to open a dialog is announced correctly by screen readers.

The SelectPanel dialog is implemented as a container with role="dialog". Focus is automatically moved to the filter input, and focus is maintained inside the dialog until it's closed.

When the dialog is opened, the dialog's heading (including any additional description) is correctly associated with the dialog container and announced by screen readers.

The dialog can be closed using Esc, or by clicking/tapping outside of the dialog. When the dialog is closed, focus is moved back to the button that opened it.

The component makes extensive use of a hidden live region container to convey information about both the currently focused filter input, the currently highlighted option where the "virtual" focus is placed, and to convey when the list of options is updated.

The input field has a standard focus indicator. The "virtual" focus is currently only conveyed by a subtle gray background.

When options are grouped, the headings/labels of the groups are currently not conveyed to screen reader users.

Keyboard navigation

Implementation requirements

Authors can add leading visuals to options in the list. However, even when providing text alternatives for these visuals, only the text label for the option is currently conveyed. Authors should only use decorative visuals, and make sure that these visuals don't convey any important content that is not already conveyed by the text label for the option.

The component allows authors to use a visually hidden label. While this means that screen reader users will still hear an appropriate label, make sure that the meaning and purpose of the SelectPanel is also clear (visually, from the overall context) to non-screen reader users.

How to test the component

Integration tests

• The component has a clear label that conveys its purpose
• If leading visuals are used, these are only decorative and don't convey any meaning/purpose that is not already apparent from the options' text

Component tests

• The <button> element has an aria-popup="dialog" to convey its purpose
• Both the component's label and its current value are conveyed as part of the <button>'s accessible name
• The SelectPanel dialog container has an implicit or explicit role="dialog"
• When the dialog is opened, focus is moved to the filter input
• The dialog's label and header content are associated with the dialog container (for instance, using aria-labelledby / aria-describedby)
• When focus is on the filter input, information is also provided to screen reader users about the secondary "virtual" focus - which item in the options list is highlighted, and what its state (selected or not selected) is
• When the list of options is updated, the new total number of options visible is conveyed to screen reader users
• The currently focused control, as well as the location of the secondary "virtual" focus, is visually conveyed; the focus indicators have sufficient contrast (at least 3:1 against their background)
• If options are grouped into separate sections, the heading/label for each section is conveyed to screen readers when the virtual focus moves through the list of options
• Pressing Esc or clicking/tapping outside of the dialog closes the dialog, focus returns to the <button> |