SelectPanel

The SelectPanel is an anchored dialog that allows users to quickly navigate and select one or multiple items from a list. It includes a text input for filtering, supports item grouping, and offers a footer for additional actions. Changes are applied upon closing the panel.

Page navigation navigation

Accessibility and usability expectations

Presentation

Cognition

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 to help orient users

Vision

Both the input field and the currently highlighted option (with "virtual" focus) must have a clear visible focus indicator
Additional controls in the footer of the panel must also have a visible focus style

Mobility

Users can dismiss the dialog with the Esc key or by clicking/tapping outside the panel, ensuring support for both keyboard and pointer input methods

Adaptability

Text resizing and spacing adjustments must be supported without loss of readability or function
The SelectPanel component must be usable without horizontal scrolling, at a viewport size of 320 by 256 CSS pixels

Interaction

Keyboard

Focus must move to the dialog when it is opened and remain within it until explicitly dismissed
- In the case of single-value SelectPanel, the dialog can be closed after the option has been selected
Focus initially lands on the filter input, and users can Tab through to any additional footer controls
The dialog can be dismissed using the Esc key
Keyboard users can use arrow keys to move "virtual" focus through the options in the list
When closed focus should return to the button that triggered the dialog

Engineering for AT Compatibility

The button that opens the SelectPanel must include both the control’s label and the currently selected value in its accessible name
The button’s functionality to open a dialog must be programmatically conveyed to screen readers
When the dialog opens, screen readers must announce the dialog’s title and any optional description
Upon opening, "real" focus is placed on the filter input, and "virtual" focus is placed on the first option, both should be communicated to screen reader users
As the user types in the filter input, the updated number of available options must be exposed to screen readers
As the user moves through the option list with the keyboard, the currently highlighted option and its selected state must be announced
When focus moves into a new group of options, the group's heading/label must be announced
Screen reader users must be able to access and understand any additional controls present in the footer of the panel

Speech recognition

The button’s accessible name must include the visible label and current value so that it can be activated using its visible name

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 grey background
When options are grouped, the headings/labels of the groups are currently not conveyed to screen reader users

Key	Description
`Tab`	Move focus forward between interactive controls and widgets within the Dialog.
`Shift + Tab`	Move focus backward between interactive controls and widgets within the Dialog.
`Enter`	Select items in the list or activate buttons or links within the SelectPanel.
`Space`	Type a space in the input or activate buttons or links within the SelectPanel.
`ArrowDown`	Navigate forward through items in the list. If focus is on the last item, `ArrowDown` moves focus to the first item.
`ArrowUp`	Navigate backward through items in the list. If focus is on the first item, `ArrowUp` moves focus to the last item.
`Home`	Move focus to the first item in the list.
`PageUp`	Move focus to the first item in the list.
`End`	Move focus to the last item in the list.
`PageDown`	Move focus to the last item in the list.
`Esc`	Apply changes and close the SelectPanel.

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>