Combobox

Editable single selection with retained async results.@gemologic/sheen · forms

Playground

label

placeholder

filter

Owner

<Combobox label="Owner" options={[{ value: "ada", label: "Ada" }]} defaultValue="ada"  filter="contains"/>

Variant matrix

App-owned results

Owner

filter: contains

Owner

filter: startsWith

Owner

filter: endsWith

Owner

filter: false

Owner

Anatomy

Package

@gemologic/sheen

Source

packages/ui/src/primitives/Combobox.tsx

Tokens

--sheen-color-bg-inset
--sheen-color-bg-raised
--sheen-color-border-control
--sheen-color-focus-ring

Accessibility

Role: comboboxKeyboard: ArrowDown, ArrowUp, Home, End, Enter, Escape

Do

Set pending before replacing externally fetched options, then publish the accepted result set atomically.

Do not

Do not commit free-form query text as the selected value.

Generated props

Name	Type	Default	Description
`value`	`string \| null`	—	Controlled selected value; null explicitly clears selection.
`defaultValue`	`string \| null`	—	Initial uncontrolled selected value.
`onValueChange`	`(value: string \| null) => void`	—	Receives committed option values, never free-form input.
`label` *	`string`	—	Required visible label.
`options` *	`readonly ComboboxOption[]`	—	Accepted options with unique nonempty values and labels.
`name`	`string`	—	Native hidden-select form name.
`form`	`string`	—	Optional external form ID.
`placeholder`	`string`	—	Text shown while the editable input is empty.
`description`	`string`	—	Supporting text associated with the input.
`error`	`string`	—	Field validation text and invalid state.
`disabled`	`boolean`	`false`	Disables input, selection, and submission.
`readOnly`	`boolean`	`false`	Allows inspection but rejects edits.
`required`	`boolean`	`false`	Requires a committed selection for native form submission.
`filter`	`ComboboxFilter`	`contains`	Built-in label filter, or false when the app supplies externally filtered options.
`onInputChange`	`(value: string) => void`	—	Receives editable query changes; the app owns debounce, cancellation, and request ordering.
`pending`	`boolean`	`false`	Retains the last accepted result nodes and prevents stale selection while the next result set is pending.
`resultsError`	`string`	—	Nonblocking async-result error; field validation remains separate.
`onRetry`	`() => void`	—	Optional retry action shown with resultsError.
`inputRef`	`(element: HTMLInputElement) => void`	—	Receives the visible native input.

Native Solid/HTML attributes remain available and are omitted from this authored-prop view.