# Combobox

Chooses one or several options from a long or rich list, with a search row that narrows it.

* Kind: component
* Page: https://design.werklist.com/components/combobox
* Version: 2.1.2

## When to use it

* A long list people search by name
* Options told apart by a flag, a photo, an icon or a hint: countries, people, time zones, stages
* Several answers from a long list

## When not to use it

* A short list of plain options: a select
* Free text that is not in the list

## Rules

* Show the search row when the list has more than 7 options
* Open upward when the room below is under 280 px and the room above is larger
* Keep the list within 70 percent of the window height, and at least 176 px tall
* Keep 8 px from the window edge

## Anatomy

* Field: the fill of the text field, 12 px padding, 8 px between its parts. It is a button with role="combobox" (--input-border)
* Leading mark: a flag of 20 px, a photo of 24 px, or an icon of 16 px in the muted ink
* Chevron: 16 px, 12 px from the end. It turns over in 150 ms while the list is open (--text-muted)
* List: as wide as the field, 8 px below it, corner radius 12 px, padding 4 px. It floats above the page and rises into place in 150 ms (--glass-fill-raised)
* List shadow: the raised shadow, with a top highlight and a fine ring in dark (--glass-shadow-raised)
* Search row: a 16 px search icon and bare text with no fill and no ring, 10 px from the edge, 36 px high, and 44 px high with 16 px text on a touch screen (--text-muted)
* Row: 36 px, at least 44 px on a touch screen, padding 8 px by 10 px, corner radius 8 px, 14 px on 20 px text that wraps (--text)
* Row hint: 12 px on 16 px at the end of the row (--text-muted)
* Check: 16 px at the end of the chosen row (--brand-blue)
* Empty line: No match for the typed text, 14 px, at the row inset (--text-muted)

## Variants

* Single: One answer. Choosing closes the list
* Several: Several answers. Each row has a checkbox and the list stays open. The field lists the choices by name. When the names do not fit, it ends with a count, such as “and 2 more”. The list carries aria-multiselectable

## Sizes

* md: height 44 px, padding 0 12 px, type 14 px on 20 px
* lg: height 48 px, padding 0 12 px, type 14 px on 20 px
* compact: height 36 px with a mouse and 44 px on a touch screen, padding 0 12 px, type 14 px on 20 px

## States

* Rest, error, disabled: As the text field, with no hover state (--input-border, --error, --text-muted)
* Focus: The field is a button and shows focus as a button does: the fill stays, and a 2 px blue outline sits 2 px outside the field (--brand-blue)
* Open: The chevron turns over, the list shows, and the field carries aria-expanded="true"
* Row under the pointer or the keyboard highlight: The same fill for both (--glass-fill-hover)
* Chosen row: A check at the end, and aria-selected="true" (--brand-blue)
* Loading: Grey placeholder rows until the options arrive
* No match: No match for the typed text (--text-muted)
* No options: The field is disabled and the hint says why

## Keyboard

* Enter, Space or Down arrow on the field: Opens the list. Focus moves to the search row, or to the list when there is no search row
* Typing: Narrows the list. Without a search row, jumps to the first option that starts with the letters
* Up and Down arrows: Move the highlight
* Home and End: First and last option
* Enter: Chooses the highlighted option and closes. With several answers, ticks or clears it and keeps the list open
* Escape: Closes this list only, so a dialog around the field stays open. Focus returns to the field
* Tab: Closes without changing the value and moves to the next control

## Accessibility

* The field is a button with role="combobox", aria-haspopup="listbox", aria-expanded and aria-controls, named by the Field label
* The search row is an input with role="combobox", aria-autocomplete="list", aria-controls and aria-activedescendant
* The list has role="listbox". Options have role="option" and aria-selected, and are not tab stops
* Escape closes only the top layer
* Focus returns to the field however the list closes
* The chosen name is cut short in the field only. Its accessible name stays whole
* With reduced motion the list only fades

## Content

* Options are parallel phrases in sentence case
* The empty line repeats the query: No match for Kenya
* The placeholder of the search row names the list: Search countries

## Tokens

* --glass-fill-input
* --input-border
* --glass-fill-raised
* --glass-blur-raised
* --glass-shadow-raised
* --glass-fill-hover
* --brand-blue
* --text
* --text-muted
* --radius-lg
* --radius-xl
* --space-1
* --space-2
* --layer-popover