# Listbox ### Screenshots No screenshot yet. ### Introduction The listbox pattern is a JavaScript widget. It allows *selection* of one or more items from a list of options. Because it is not a form control, the value will not be passed to the server without the help of some client-side JavaScript. A listbox can be self-contained, or be controlled by another widget (e.g. in a [combobox](/mindpatterns/input/combobox.md) pattern, the textbox *controls* the listbox). ### Known Issues These are all known *serious* issues with assistive technology in relation to this pattern: * * ### Working Examples Experience the pattern in action on our companion [eBay MIND Patterns examples website](https://ebay.github.io/mindpatterns/input/listbox/index.html). Examine the required markup structure in our our [Bones GitHub project](https://github.com/ianmcburnie/bones#user-content-listbox). View a fully styled example in our [eBay Skin CSS framework](https://opensource.ebay.com/skin/component/listbox/). ### Terminology * **widget**: the pattern as a whole, comprised of the parts below * **listbox:** contains a list of options * **option**: each option available for selection * **checked**: state of each option (checked or unchecked) ### Configuration * **autoSelect:** a listbox with auto select will update its checked state automatically as a user navigates with arrow keys (similar to a radio button group). * **multiSelect**: a listbox with multiSelect allows more than one option to be selected * **owner**: specify the focusable element that will own and control the listbox programmatically (e.g. a [combobox](/mindpatterns/input/combobox.md)). ### Best Practices This section is not yet available. ### Interaction Design This section provides interaction design for keyboard, screen reader & pointing devices. #### Keyboard If the listbox has no owner, the listbox **must** be keyboard focusable. If a listbox has keyboard focus, `UP-ARROW` and `DOWN-ARROW` keys must change the highlighted option (skipping any that are disabled). For a focusable listbox, keyboard focus will *appear* to be at two places at the same time (the listbox and the options). In actual fact, keyboard focus always stays on the listbox. The [aria-activedescendant](http://www.w3.org/TR/wai-aria/states_and_properties#aria-activedescendant) property controls the pseudo-focus inside of the listbox and we can use CSS to style the active descendant. For a listbox with `autoSelect` configuration, highlighting an option **must** also select that option (i.e. `aria-checked="true"`). For a listbox without `autoSelect` configutation, a highlighted option must be manually selected using the `SPACEBAR` or `ENTER` key. #### Screen Reader With virtual cursor on listbox, screen reader should announce role of listbox. The checked state of an option **must** be announced. Disabled options must be announced as disabled. #### Pointer Clicking or tapping button will toggle expanded state of flyout. Clicking or tapping option in flyout will update button to that value. ### Developer Guide This section is not yet available. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ebay.gitbook.io/mindpatterns/input/listbox.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.