# Combobox _Box Kite 2.1.0 · a markdown copy of https://www.box-kite.dev/combobox/_ A text field over a list of your own rows: APG's editable combobox, object values, a filter you can compose, chips, and a create row. **Import** ```jsx import Combobox from '@box-kite/react/components/combobox'; ``` **Usage** ```jsx assign(person)} /> ``` ## A row in is a row out `data` is the list you already have, and the value is one of _those rows_ — not a string dug out of one. `onValueChange` hands the object straight back, typed, so there is no lookup table on the other side of the handler. That is the complaint every string-only select collects, and it is the reason this component exists. `def` is how a row is read: `label` is its text — searched, displayed and read out — and `key` is what makes two rows the same row, so a list refetched from the server still shows the selection as chosen. Both take a key of the row or a function. `disabled` and `display` are the other two. ```jsx `${p.name} · ${p.team}`, key: 'id', disabled: 'away' }} label="Reviewer" /> ``` ## Several rows are chips `multiple` puts the selection in front of the field as chips and turns the value into an array — the one shape decision that cannot be read off the value itself, because a combobox usually starts with nothing in it. Choosing a row that is already chosen takes it off again. A chip's remove button is deliberately **not** a tab stop: twenty selections would otherwise cost twenty presses to Tab past. `Backspace` on an empty field removes the last one, and the listbox toggles any row back off, so nothing here needs a mouse. ```jsx ``` ## The filter is yours to compose The built-in one folds case and strips accents, so `jose` finds `José`, and matches anywhere in the label rather than only at the front. `filter` replaces it, and it takes the _whole list_ so it can rank as well as reject — it is handed the label reader, so starting from the built-in one costs nothing. ```jsx ComboboxUtils.filterRows(rows, query, labelOf).slice(0, 3)} /> ``` ## A server that already searched `filter={false}` says the data arrived filtered, so nothing is thrown away a second time. `onQueryChange` is the hook the request hangs off, and `loading` makes the popup say the rows are coming rather than that there are none — which is the difference between "still looking" and "nothing here". ```jsx search(query)} /> ``` ## A row that is not there yet `createRow` turns what was typed into the row it would make, or returns `null` to refuse it. Its presence is what offers the create row at all, and one is never offered for a query a row already answers by name — offering "Create Design" beside Design is how a list grows twins. The change arrives with reason `create`. ```jsx ({ id: query, name: query })} /> ``` ## Ten thousand options A list past a hundred rows is windowed: the popup renders the dozen on screen and a few either side, so it opens in one frame whether it holds a hundred rows or ten thousand. Nothing about the rest of the component changes — the filter still runs over the whole list, the arrows still walk all of it, and the value is still the row you passed in. ```jsx ``` The row height is measured rather than declared, so a restyled option windows correctly on its own. What windowing assumes is that rows are all the _same_ height — a `display` that varies one wants `virtualize={false}`, which renders every row however many there are. `virtualize` also takes `true` to window a short list and an object to tune it: `threshold` is the row count it starts at, `overscan` how many rows are kept either side, and `itemHeight` the pitch, when it should be stated rather than measured. The half of this that is not performance is the ARIA. A windowed listbox holds a slice of its rows, so every option carries `aria-setsize` and `aria-posinset` — without them a screen reader would announce “Person 1 of 15” on a list of ten thousand. And the row the keyboard is on is always rendered, whatever the scroll position says: `aria-activedescendant` naming a row that was never put in the DOM names nothing at all, so the window goes where the keyboard is and lets the scroll catch up. ## What the keyboard does It is APG's editable combobox. Typing filters and never highlights a suggestion — that is _list_ autocomplete, not inline, and a highlight nobody asked for is one `Tab` away from being committed. The arrows move through what the filter left; `Home`, `End` and the sideways arrows move the caret and hand the highlight back to the field; `Enter` chooses the highlighted row and does nothing when there is none. `Escape` closes the listbox keeping what was typed, and a second one clears the field. The whole control is one tab stop however many options are open, because DOM focus never leaves the input — the listbox is named by `aria-activedescendant` instead. ## Styling Every part is a node of the `combobox` style tree: `combobox.label`, `combobox.field`, `combobox.chip` and its `combobox.remove`, `combobox.icon`, `combobox.items`, `combobox.item` and `combobox.message`. The one that is not yours is `combobox.window`, what a windowed listbox renders its slice into. A row's chosen state is its own `aria-selected`, and where the keyboard is is the `highlighted` variant — a listbox driven by `aria-activedescendant` holds DOM focus nowhere, so `:focus-within` never fires and the highlight has to be drawn from state. ```jsx ``` ## The whole pattern, in one component A combobox is usually assembled: a behaviour package for the state machine, then the markup, the styling and the ARIA written around it. This is 8.65 KB on top of Box with all of it inside — the listbox, the chips, the create row and the windowing — so what you write is the data and what it means. ```jsx ({ id: query, name: query })} /> ``` Ten thousand rows, several selected as chips, a query that can become a row, and the value that comes back is one of the objects that went in — not its label. Those three are what a string-only API cannot do. ## Combobox props Everything below is this component’s own. All 235 of Box’s style props work on it too, and those are on [/box](https://www.box-kite.dev/box.md) rather than repeated here. | Prop | Type | Default | What it does | | --- | --- | --- | --- | | `data`required | `TRow[]` | — | Every row the combobox can offer. Filtered by the query unless `filter` is `false`. | | `def`required | `ComboboxDef` | — | How to read a row: its `label` (the text, which is searched and read out), its `key` (what makes two rows the same row), and optionally `disabled` and `display`. A key of the row, or a function. | | `label` | `React.ReactNode` | — | The combobox's name, rendered above it in a real `