Kwark. Design System
Open Kwark

Combobox

A field that suggests answers but always keeps what you type. Choices are a help, never a gate.

ComponentsSelectionIn the app
<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 onChange on 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.

Do

A red No matching option that refuses the writer’s own location until someone adds it to a list.

Don’t

Anatomy

  1. Input: the shared Text input box with 44px reserved on the right (padding-inline-end: var(--k-tap)). Placeholder Choose or type.
  2. Chevron: a 44px-wide icon button filling the input’s height, 14px glyph in --k-text-2; it turns 180° while open.
  3. 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.
  4. Option: 44px tall, 8px 12px padding, 6px corners, 14px text that wraps anywhere. Active and current: --k-raise.
  5. Keep your own answer: a presentation row in --k-text-2 when 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" with aria-autocomplete="list" (or "none" when choose-only), aria-expanded, aria-controls while open, and aria-activedescendant for the active option. Focus never leaves the input.
  • The list is role="listbox" named Location choices; options have aria-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 Combobox from 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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…