05 · Forms

alpha

Combobox

An editable single-select text field that filters a labelled option collection and submits the selected key.

Since: 1.0.0-next.0
Owner: Brand Core
Export: PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED/Combobox
Release: Documentation version

Deterministic fixture · default state

Component studio

light · comfortable · LTR

§01

Contract

Semantics first

Anatomy

Uses an input role=combobox with aria-activedescendant and a linked listbox popup; DOM focus stays on the input.

Consumer classes, styles, and data attributes may extend the surface, but required roles, IDs, relationships, and handlers remain owned by the component.

Keyboard

Arrow Up/Down opens the list and moves the active option.
Home/End move to collection boundaries while open.
Enter selects the active option.
Escape closes without changing the current text.
Native text editing remains available while the popup is open.

§02

Public surface

API & styling

Props

id: Explicit IDs override stable generated IDs.
class / style: Consumer additions compose with required styles.
ref: Element or callback where focus control is expected.
children: Typed content; raw HTML strings are never rendered.

Slots & events

children: Primary content slot.
onChange: Typed value plus a small reason object when state changes.
native events: Composed without overwriting required handlers.

State attributes

data-fui-combobox
data-fui-state="open|closed"
data-fui-control
data-fui-listbox
data-fui-active
data-fui-selected
data-fui-disabled
data-fui-invalid

CSS tokens

--fui-field-*
--fui-combobox-*
--fui-listbox-*
--fui-option-*

§03

Consumption

Solid, Vite & Astro

Solid / VitePRIVATE_BETA_PACKAGE_COORDINATE_REDACTED/Combobox

import Combobox from 'PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED/Combobox';

<Combobox>Frauthy content</Combobox>

Astroisland

---
import Combobox from 'PRIVATE_BETA_PACKAGE_COORDINATE_REDACTED/Combobox';
---

<Combobox client:visible>Frauthy content</Combobox>

§04

Verification

Evidence record

Scheduled

Automated

Batch D collection tests cover controlled selection/input, filtering, active descendant, keyboard choice, disabled/read-only state, reset, empty results, and form value.

Target: Brand 1.0.0-next.0 matrix
Last verified: Pending integrated G2 run

Required

Assistive technology

Pending VoiceOver/Safari, NVDA/Firefox, TalkBack/Chrome, and VoiceOver/iOS; touch AT evidence blocks beta.

Desktop: VoiceOver/Safari · NVDA/Firefox
Touch: Required for touch-centric behavior

Open

Known issues

The popup is currently inline rather than positioned through the overlay stack.
Filtering is local substring matching; async results, virtualization, and custom filter policies are deferred.

§05

Editorial guidance

Do / don’t

Provide stable keys and textValue for every option and keep the option set responsive to the typed query.

Don’t

Do not use Combobox when users cannot predict what text matches or when a native select is sufficient.

Release activity

Combobox · Brand Core

1 recorded change · 26 weeks

2026-07-13
1.0.0-next.3
Baseline public component contract.

Version & provenance

New in the v2 architecture

There is no stable predecessor for this explicit compiled subpath. The v1 compatibility layer remains tested separately; visual and API diffs begin with the next prerelease.

Current: 1.0.0-next.0
Previous: compatibility surface
Deprecation: none
Replacement: not applicable

Next in FormsSlider