<div class="kw-specimen-row">
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="option" aria-selected="true">Edit suite</li><li role="option" aria-selected="false">Edit suite corridor</li></ul></span></label>
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Rooftop of the lab" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="presentation">Keep your own answer</li></ul></span></label>
</div>
<div class="kw-specimen-row">
<label class="kw-field"><span class="kw-label">Height unit</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Feet and inches" role="combobox" aria-autocomplete="none" aria-expanded="false" readonly autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Height unit" aria-haspopup="listbox" aria-expanded="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span></span><span class="kw-hint">Choose only: Space opens the list.</span></label>
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit suite" aria-readonly="true" readonly></span></span><span class="kw-hint">Read only: no chevron, no list.</span></label>
</div>
What it is
The app’s Combobox (components/ui/Combobox.tsx) is a text field with suggestions. Its first line of source says the rule: a choice is a suggestion: typing an answer never requires adding an option first. Type Rooftop of the lab when the list only knows Edit suite, and the field keeps it; the list says Keep your own answer instead of No results.
It has two modes:
- Editable (default): type to filter, or open the full list with the chevron. Used for locations, props and any answer the writer may know better than the list.
- Choose only (
editable={false}): the input is read-only and opens the list on click or Space. Used where the value must be one of a few, such as the measurement unit on a character sheet (CharacterFieldControls.tsx: Centimetres, Feet and inches, As written).
When to use
- One answer, with a list of likely ones and the freedom to write another.
When not to
- The value must be an existing record with an ID (a scene, a crew member): restrict it and say so, or use a Select.
- Several answers: Multiselect.
- Searching to navigate somewhere: Search field.
Behaviour (from the source)
- Typing calls
onChangeon every keystroke and filters by contains, ignoring case. - The list opens below, or above when there is more room above (it measures
options.length × 44 + 8, up to 256px). - Down and Up move the active option; Enter takes it; Escape closes without changing; Tab closes.
- The chevron is an Icon button named Choices for Location; pressing it opens the full, unfiltered list.
- Closing on blur: the list closes when focus leaves the whole control.
Rooftop of the lab stays in the field, with Keep your own answer under it.
A red No matching option that refuses the writer’s own location until someone adds it to a list.
Anatomy
- Input: the shared Text input box with 44px reserved on the right (
padding-inline-end: var(--k-tap)). Placeholder Choose or type. - Chevron: a 44px-wide icon button filling the input’s height, 14px glyph in
--k-text-2; it turns 180° while open. - List: 4px below the input, as wide as it, at most 256px tall then scrolls. 4px padding, 1px
--k-line, 6px corners,--k-surface. The app draws it with a line and no shadow. - Option: 44px tall, 8px 12px padding, 6px corners, 14px text that wraps anywhere. Active and current:
--k-raise. - Keep your own answer: a presentation row in
--k-text-2when nothing matches.
The specimen shows the list in the page flow; in the app it is absolutely positioned (.k-combobox > ul) and stacks above neighbours with --ds-z-high.
Tokens
| Token | Light | Dark |
|---|---|---|
--k-surface |
#ffffff | #1a1a1a |
--k-bg |
#f8fafc | #191919 |
--k-raise |
#f1f5f9 | #252525 |
--k-line |
#e2e8f0 | rgba(255, 255, 255, .1) |
--k-text |
#0f172a | #e3e3e3 |
--k-text-2 |
#5b6779 | #9ca3af |
--k-accent-soft |
#e8b58b | #e8b58b |
--k-tap |
44px | |
--k-radius-control |
6px | |
--k-fs-body |
14px |
React
In the Kwark app: import Combobox from '@/components/ui/Combobox'.
<Combobox id="location" label="Location" value={location}
onChange={setLocation} options={['Edit suite', 'Edit suite corridor', 'Rooftop']} />
// Choose only (no typing), as the measurement unit on a character sheet:
<Combobox id={`${id}-units`} label="Height unit" editable={false}
value="Feet and inches" options={['Centimetres', 'Feet and inches', 'As written']} onChange={chooseUnit} />
| Prop | Type | Notes |
|---|---|---|
id |
string |
Stable field ID; the list items are named from it. |
label |
string |
Becomes the input’s aria-label and the chevron’s name (Choices for Location). |
value |
string |
What the field holds; may be text that is not an option. |
options |
string[] |
Suggestions, filtered by what is typed. |
onChange |
(value: string) => void |
Called on every keystroke and every choice. |
editable |
boolean |
Default true. False makes it choose-only: Space or click opens the list. |
readOnly |
boolean |
Hides the chevron and the list. |
HTML and CSS
Works anywhere with kwark.css.
<div class="kw-specimen-row">
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="option" aria-selected="true">Edit suite</li><li role="option" aria-selected="false">Edit suite corridor</li></ul></span></label>
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Rooftop of the lab" role="combobox" aria-autocomplete="list" aria-expanded="true" placeholder="Choose or type" autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Location" aria-haspopup="listbox" aria-expanded="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span><ul class="kw-combo__list" role="listbox" aria-label="Location choices"><li role="presentation">Keep your own answer</li></ul></span></label>
</div>
<div class="kw-specimen-row">
<label class="kw-field"><span class="kw-label">Height unit</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Feet and inches" role="combobox" aria-autocomplete="none" aria-expanded="false" readonly autocomplete="off"><button class="kw-ibtn" type="button" aria-label="Choices for Height unit" aria-haspopup="listbox" aria-expanded="false"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button></span></span><span class="kw-hint">Choose only: Space opens the list.</span></label>
<label class="kw-field"><span class="kw-label">Location</span><span class="kw-combo"><span class="kw-combo__field"><input class="kw-input" type="text" value="Edit suite" aria-readonly="true" readonly></span></span><span class="kw-hint">Read only: no chevron, no list.</span></label>
</div>
Keyboard
| Key | Editable | Choose only |
|---|---|---|
| Typing | Filters and opens | — |
| Space | Types a space | Opens or closes |
| Down / Up | Opens; moves the active option | Same |
| Home / End | Moves the text caret | First and last option |
| Enter | Takes the active option | Same |
| Escape | Closes without changing | Same |
Roles and names
- The input is
role="combobox"witharia-autocomplete="list"(or"none"when choose-only),aria-expanded,aria-controlswhile open, andaria-activedescendantfor the active option. Focus never leaves the input. - The list is
role="listbox"named Location choices; options havearia-selected. - The empty row is
role="presentation", so it is not offered as a choice. - The chevron is
aria-haspopup="listbox"and does not take focus from the input on mouse down.
Rules
- Must keep text the person typed when it matches no option; show “Keep your own answer”, never an error.
- Must use the shared
Comboboxfrom components/ui; never a native<datalist>. - Always name the chevron “Choices for” and the field’s label.
- Never move focus into the list; use aria-activedescendant from the input.
- Always use choose-only mode (editable={false}) when the value must be one of a fixed few.
AI readiness test
Task. Add a Location field to the scene details panel.
Give the agent. Combobox, Text input.
Constraint. Locations come from the project, but the writer may name a new one.
A reliable answer
- Uses the shared Combobox
- Placeholder Choose or type
- Typed new location is kept
- Keep your own answer when nothing matches
- Chevron named Choices for Location