diff --git a/README.md b/README.md index 4f5a5a1..06a20ca 100644 --- a/README.md +++ b/README.md @@ -108,3 +108,18 @@ These settings are available: npm install npm test ``` + +## Troubleshooting + +### Combobox options must have unique IDs + +Passing a combobox whose options lack IDs results in the following console warning. + +> Combobox options must have unique IDs +> See https://github.com/github/combobox-nav/?tab=readme-ov-file#combobox-options-must-have-unique-ids + +Without the IDs we lack a unique identifier for [`aria-activedescendant`](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant) to reference. As a result, screen readers are unable to announce which option is currently selected. + +You can remove this warning by setting IDs on every option in the combobox. + + diff --git a/src/index.ts b/src/index.ts index 35efe6e..9fe1d5e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -49,6 +49,13 @@ export default class Combobox { list.id = `combobox-${Math.random().toString().slice(2, 6)}` } + if (list.querySelectorAll('[role="option"]:not([id])').length > 0) { + console.warn([ + 'Combobox options must have unique IDs', + 'See https://github.com/github/combobox-nav/?tab=readme-ov-file#combobox-options-must-have-unique-ids', + ].join('\n')) + } + this.ctrlBindings = !!navigator.userAgent.match(/Macintosh/) this.keyboardEventHandler = event => keyboardBindings(event, this)