Combobox
A text field that filters a list of options as you type and stores the one picked. For long lists and server-backed options; it says so when nothing matches.
Usage
Use it when
- One value from a long list people know by name: province, city, school, university, major.
- Options come from a server as you type (React
ComboboxwithloadOptions). - People know what they want and typing three letters is faster than scrolling.
Use something else when
- A short fixed list (under about 30 options): use Select.
- Searching to filter a page or list, without storing a choice: use Search field.
- Several values, including new ones people make up: use Tag input.
- Jumping to any page or command in the app: use Command palette.
- Two to five options: use Radio.
Where it goes. In a form like a text field, or in a filter bar on wide screens. The list opens below the field, as wide as the field, and scrolls inside (up to 320 px or half the viewport).
Examples
<div class="field" style="max-width: 360px; width: 100%;">
<label class="field__label" for="cb-prov">Province</label>
<div class="select combobox" data-lds-combobox>
<div class="control combobox__control"><span class="ic" aria-hidden="true">location_on</span><input id="cb-prov" role="combobox" placeholder="All provinces"><span class="control__btn combobox__arrow" aria-hidden="true"><span class="ic">expand_more</span></span></div>
<ul class="menu select__menu" role="listbox" aria-label="Province">
<li class="menu__item" role="option" data-value="jabar">West Java</li>
<li class="menu__item" role="option" data-value="jateng">Central Java</li>
<li class="menu__item" role="option" data-value="jatim">East Java</li>
<li class="menu__item" role="option" data-value="bali">Bali</li>
<li class="menu__item" role="option" data-value="kalbar">West Kalimantan</li>
<li class="menu__item" role="option" data-value="kaltim">East Kalimantan</li>
<li class="menu__item" role="option" data-value="sulsel">South Sulawesi</li>
<li class="menu__item" role="option" data-value="papua">Papua</li>
<li class="select__empty" role="presentation" hidden>Nothing matches. Try other words.</li>
</ul>
</div>
</div>loadOptions the query is debounced (180 ms) and the previous request is aborted when the text changes; a spinner shows in the field while loading. minChars waits for enough letters.<Combobox
label="University"
icon="school"
value={uni}
onChange={setUni}
minChars={3}
loadOptions={(q, signal) =>
fetch(`/api/universities?q=${encodeURIComponent(q)}`, { signal }).then((r) => r.json())
}
/>Anatomy
| Part | What it is |
|---|---|
.select.combobox | Required. Positioned wrapper. data-lds-combobox for the plain HTML behavior. |
.control.combobox__control | Required. The 44 px field; .is-open while the list shows. A leading .ic is optional. |
input[role=combobox] | Required. The text input, named by a <label for> or aria-label. The JS sets aria-expanded, aria-controls, aria-autocomplete="list" and autocomplete="off". |
.control__btn.combobox__arrow | Optional chevron (aria-hidden), rotates while open. In React a clear button replaces it once a value is chosen. |
ul.menu.select__menu[role=listbox] | Required. The options; li.menu__item[role=option] with data-value. |
.select__empty | Required. The no-match row, role="presentation", hidden until nothing matches. |
States
| State | How |
|---|---|
closed | Looks like a text field with a chevron. |
open (.is-open on the control, aria-expanded="true") | Accent edge and halo stay on; chevron points up; the list grows in. |
filtering | Rows that do not contain the text get hidden; the first visible row is highlighted. |
no match | .select__empty shows "Nothing matches. Try other words." |
loading (React) | A spinner in the field replaces the chevron. |
chosen (React) | A clear .control__btn (close icon, labelled "Clear Province") replaces the chevron. |
Motion and microinteractions
- The list uses the menu motion: in on
--spring-smooth(560 ms) fromscale(0.96) translateY(-4px)with opacity in--d-fast; out in--d-exit(180 ms) on--ease-exit. - Filtering hides rows at once; do not animate rows in and out on every key, it makes the list feel slow.
- The chevron rotates on
--spring-smooth. Highlight follows the pointer in 60 ms linear. - Reduced motion: the menu fades in 120 ms linear without scale.
Accessibility
- The input has
role="combobox",aria-expanded,aria-controlsandaria-autocomplete="list";aria-activedescendantpoints at the highlighted option while focus stays in the input. - Keys: Down opens and moves, Up moves, Enter picks, Escape closes (React also restores the chosen label), Tab closes.
- The empty row is
role="presentation"; consider anaria-live="polite"count if results change a lot. - Filtering matches anywhere in the label (and the second line in React), case-insensitive.
Do and don't
Do
- Put the most likely options first when the field is empty.
- Set
minChars(2 or 3) for server lists so the first request is useful. - Show the second line (
sub) when two options share a name.
Don't
- Accept free text that matches no option as the value; a combobox stores one of its options.
- Use a combobox for a short list just to look searchable.
Behavior and code
Plain HTML. data-lds-combobox on .select.combobox: focus selects the text and opens; typing filters the options and toggles .select__empty; keys as above; a pick writes the label into the input and fires lds:change with { value, label }. Server loading and the clear button exist only in the React binding.
React. From lampung-design-system/react.
import { Combobox } from 'lampung-design-system/react';
// Local options, filtered in the browser
<Combobox label="Province" icon="location_on" value={prov} onChange={setProv}
options={[{ value: 'jabar', label: 'West Java' }, { value: 'bali', label: 'Bali' }]} />
// From a server: debounced 180 ms, aborted when the query changes
<Combobox label="University" icon="school" value={uni} onChange={setUni} minChars={3}
loadOptions={(q, signal) => fetch(`/api/universities?q=${q}`, { signal }).then((r) => r.json())}
emptyText="No university by that name. Check the spelling." />