intro

Combobox

A highly interactive organism that marries a TextInput with an OptionGroup-like dropdown.

Combobox

The Combobox component combines a TextInput with an OptionGroup dropdown, allowing users to filter and select from large lists of options efficiently. It adheres to the Curva & Concreto doctrine by relying on native input forms and strict popover lists.

Basic Combobox

Select a State

function helper($$renderer) { $$renderer.push(`Start typing to filter the ${$.escape(states.length)} available states.`); }

Current Value: None selected

Validation State

Destination State

function error($$renderer) { $$renderer.push(`This state is not currently serviced. Please select another.`); }

Sizes

Small Combobox

Medium Combobox

Large Combobox

Disabled State

Historical Region

function helper($$renderer) { $$renderer.push(`This selection cannot be changed.`); }

Usage

The Combobox is designed to be composed within a FormField component. It automatically inherits the id, aria-describedby for error/helper linking, and invalid state via context.

<script>
  import { FormField, Combobox } from 'cobogo';

  let stateValue = $state('');
  const states = [
    { value: 'sp', label: 'São Paulo' },
    { value: 'rj', label: 'Rio de Janeiro' },
    { value: 'mg', label: 'Minas Gerais' },
    // ...
  ];
</script>

<FormField id="state-select" label="Select a State">
  <Combobox options={states} bind:value={stateValue} placeholder="Type to filter..." />
  {#snippet helper()}
    <p>Start typing to filter available states.</p>
  {/snippet}
</FormField>

Props

Prop	Type	Default	Description
`value`	`string`	`''`	The bindable selected value matching an option’s `value`.
`options`	`Array<{value: string, label: string}>`	`[]`	The array of available options to filter and select from.
`placeholder`	`string`	`''`	Placeholder text for the input when empty.
`disabled`	`boolean`	`false`	Disables the entire combobox interaction.
`invalid`	`boolean`	`false`	Forces the invalid (error) state. Usually inherited from `FormField`.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	The size variant of the combobox.
`...rest`	`any`	-	Standard HTML input attributes forwarded to the underlying input.

Variants

Sizes

The Combobox component supports three sizes: sm, md, and lg, matching the TextInput atom.

<Combobox size="sm" options={opts} />
<Combobox size="md" options={opts} />
<Combobox size="lg" options={opts} />

Invalid State

The invalid state maps the background color to var(--vermelho-soft) and changes the borders and focus outlines to var(--vermelho).

<FormField id="state-invalid" label="State" invalid>
  <Combobox options={states} />
  {#snippet error()}
    <p>Please select a valid option.</p>
  {/snippet}
</FormField>

Accessibility

The component uses role="combobox" and role="listbox" appropriately.
Keyboard navigation is fully supported (ArrowUp, ArrowDown, Enter to select, Escape to close).
Focus is managed properly: returns to input on selection, active descendant links visual focus to screen readers.
Inherits aria-describedby directly from the FormField wrapper.
Respects prefers-reduced-motion for interaction animations like chevron rotation.