This page documents the VoiceOver experience when using the <auro-select> component. It covers announcements, gestures, and workflows for both large and small viewports.
When focus is given to the component trigger the following is announced:
label slot content| State | What gets announced |
|---|---|
| Expanded | "collapsed" or "expanded" |
| Required | "required" |
| Invalid | The trigger itself does not carry aria-invalid; the invalid state is announced through the alert-role Help Text (see Invalid below), not as a state hint on focus. |
| Disabled | "dimmed" |
| autocomplete | "has auto complete" |
helptext slot content if present (after a brief pause)Announces each option "[option label], ["selected" if selected], ["dimmed" if disabled]" as you move.
3 finger swipe gesture may be used to scroll the option list.
The component may be closed | collapsed using a gesture.
When the component is closed | collapsed announces the expanded state change.
Examples: large tablet, typical size or larger desktop browser window
selected]".
disabled options can not be active, this state would never be included in this announcement.
~OR~
Close | Collapse without selecting an option: Collapses the list, announces the expanded state change.Examples: mobile phone, very small desktop browser window
selected]".
disabled options can not be active, this state would never be included in this announcement.
~OR~
Close | Collapse without selecting an option: Closes the fullscreen modal dialog, announces the expanded state change.Key characteristics across both platforms:
label is always read first.aria-multiselectable="true" is applied to the internal <auro-menu> (the listbox), not to the trigger.disabled options are announced as "dimmed" and cannot be selected.What VoiceOver does:
Key distinction from aria-hidden: A disabled element is reachable but not operable. If you want VoiceOver to skip it entirely, you would need aria-hidden="true" or tabindex="-1", but that is generally not recommended for disabled controls — users benefit from knowing the field exists and why it may be unavailable.
This is consistent across NVDA and JAWS as well, though the announcement wording differs (e.g., NVDA says "unavailable").
Examples: large tablet, typical size or larger desktop browser window
Examples: mobile phone, very small desktop browser window
Key differences from single-select:
| Single | Multi | |
|---|---|---|
| Trigger role | combo box | combo box (with aria-multiselectable="true" on the internal listbox) |
| Interaction model | Open → pick → auto close | Open → toggle items → manually close |
| Value announcement |
Current selected value
On focus: Announces "[component label], [current value or 'no selection'], combo box"
|
Each option's selected state individually
On focus: Announces "[component label], [[{option label, 'selected'}, {option label, 'selected'}] or 'no selection'], combo box"
On selection change: Announces "[option label], ['selected' | 'not selected']"
|
| Space key | Opens/closes picker | Opens/closes picker — Enter toggles the active option's selection. Space does not toggle selection in multi-select. |
<auro-select multiSelect> in favor of checkboxes or other patterns that make multi-selection more discoverable.When an <auro-select> becomes invalid the following occurs:
role="alert" and aria-live="assertive", so VoiceOver announces the error message immediately when the state transitions to invalid — the announcement does not wait for the next focus.aria-invalid, so VoiceOver does not include the words "invalid data" (macOS) or "invalid entry" (iOS) as part of the trigger's own announcement. The invalid state is conveyed entirely through the alert-role help text.Example: when the select becomes invalid, VoiceOver announces the error message (e.g., "Please select a country") via the assertive alert. On the next focus of the trigger, VoiceOver announces something like "Country, no selection, combo box, Please select a country".
The following implementation details are relevant when debugging or verifying VoiceOver behavior in <auro-select>:
Focus remains on the trigger while the bib is open; the currently active option is exposed via aria-activedescendant. Because the trigger and the option live in different shadow roots, the code sets trigger.ariaActiveDescendantElement (the IDL/property form) rather than the string attribute alone — this is what allows VoiceOver to announce the active option's label and state across the shadow boundary.
Each option is stamped with aria-setsize (total count of navigable options) and aria-posinset (its 1-based position). Stamping runs on initial menu configuration and again whenever auroMenu-optionsChange fires (options added, removed, or otherwise re-initialized), so VoiceOver's "N of M" announcement stays accurate across dynamic option lists. A pure value change does not re-stamp on its own — it only updates selection state — unless it triggers a menu re-initialization in an empty/deferred-match path.
Selection-change announcements (single-select confirmation and multi-select toggle wording) are written into an aria-live="polite" span that lives in the host component's shadow root by default. In fullscreen mode the trigger becomes inert and everything outside the <dialog> is hidden from assistive tech — so the live region is routed into the bib's shadow root instead, ensuring the announcement is reachable while the dialog is open.
Selection announcements are delayed briefly (~300ms) so the option's "selected" / "not selected" announcement is not overridden by the "collapsed" announcement that follows when the bib closes.
When the fullscreen dialog opens, focus moves to the dialog's Close button and the trigger is marked inert so screen readers cannot reach it — the user is effectively inside the dialog until it closes, at which point focus returns to the trigger and inert is removed.