Combobox

The <x-wirekit::combobox> component is a searchable select that filters options as the user types. It implements the WAI-ARIA 1.2 Combobox pattern with full keyboard navigation.

Usage

<x-wirekit::combobox
    name="country"
    label="Country"
    :options="[
        'de' => 'Germany',
        'fr' => 'France',
        'es' => 'Spain',
        'it' => 'Italy',
        'nl' => 'Netherlands',
        'be' => 'Belgium',
        'at' => 'Austria',
        'ch' => 'Switzerland',
    ]"
    placeholder="Search countries..."
/>

With Preselected Value

<x-wirekit::combobox
    name="framework"
    label="Framework"
    value="laravel"
    :options="[
        'laravel' => 'Laravel',
        'symfony' => 'Symfony',
        'django' => 'Django',
        'rails' => 'Ruby on Rails',
        'express' => 'Express.js',
    ]"
/>

The value prop matches an option's value key — the label is looked up and pre-filled into the search input on load.

Disabled Options

Pass disabled => true on an option to render it dimmed and non-interactive — keyboard arrow-navigation skips it, mouse hover doesn't highlight it, click + Enter ignore it. Useful for premium-tier features, "coming soon" entries, or context-locked options:

<x-wirekit::combobox
    name="plan"
    label="Plan"
    placeholder="Select a plan..."
    :options="[
        ['value' => 'free', 'label' => 'Free — 5 projects'],
        ['value' => 'starter', 'label' => 'Starter — 25 projects'],
        ['value' => 'pro', 'label' => 'Pro — Unlimited (upgrade required)', 'disabled' => true],
        ['value' => 'enterprise', 'label' => 'Enterprise — Contact sales', 'disabled' => true],
    ]"
/>

The aria-disabled="true" attribute on disabled options keeps screen readers correctly informed.

Grouped Options

Organize options under headings by passing a nested array — a group is an array value keyed by its group label, mirroring <x-wirekit::select>. Each group renders as a role="group" with an accessible label; filtering hides empty groups automatically, and arrow-key navigation flows across the group boundaries as one continuous list:

<x-wirekit::combobox
    name="timezone"
    label="Timezone"
    placeholder="Search timezones..."
    :options="[
        'Europe' => ['cet' => 'Central European (CET)', 'gmt' => 'Greenwich Mean (GMT)', 'eet' => 'Eastern European (EET)'],
        'Americas' => ['est' => 'Eastern (EST)', 'pst' => 'Pacific (PST)'],
        'Asia' => ['jst' => 'Japan (JST)', 'ist' => 'India (IST)'],
    ]"
/>

Size Variants

<x-wirekit::combobox name="c-sm" label="Small" size="sm" :options="['a' => 'Apple', 'b' => 'Banana', 'c' => 'Cherry']" placeholder="Small..." />

<x-wirekit::combobox name="c-md" label="Medium" size="md" :options="['a' => 'Apple', 'b' => 'Banana', 'c' => 'Cherry']" placeholder="Medium..." />

<x-wirekit::combobox name="c-lg" label="Large" size="lg" :options="['a' => 'Apple', 'b' => 'Banana', 'c' => 'Cherry']" placeholder="Large..." />

Width

Like all WireKit form components, the combobox fills its container (w-full). Control the width via the parent element:

<x-wirekit::combobox
    name="country-narrow"
    label="Country"
    placeholder="Search countries…"
    :options="['de' => 'Germany', 'fr' => 'France', 'es' => 'Spain', 'it' => 'Italy', 'nl' => 'Netherlands']"
/>

<div class="max-w-sm">
    <x-wirekit::combobox label="Country" name="country" :options="$countries" />
</div>

See Input — Width for more layout examples (grid columns, mixed widths).

Options Format

The options prop accepts four formats:

{{-- Associative: key => label --}}
:options="['de' => 'Germany', 'fr' => 'France']"

{{-- List of strings (value === label) --}}
:options="['Apple', 'Banana', 'Cherry']"

{{-- List of arrays --}}
:options="[
    ['value' => 'de', 'label' => 'Germany'],
    ['value' => 'fr', 'label' => 'France'],
]"

{{-- Grouped: group label => sub-options (any of the shapes above) --}}
:options="[
    'Europe' => ['de' => 'Germany', 'fr' => 'France'],
    'Asia' => ['jp' => 'Japan'],
]"

Form Submission

The selected value (not label) is submitted via a hidden <input type="hidden"> with the given name. The visible text input is for search + display only.

Livewire Integration

<x-wirekit::combobox> keeps its selected value in internal state seeded from the value prop, so when binding with Livewire pass the bound property as :value alongside wire:model to seed the initial selection:

<x-wirekit::combobox wire:model.live="country" :value="$country" :options="$countries" />

Without :value the combobox shows its placeholder until the user picks an option; wire:model keeps it in sync afterward. This is the framework-agnostic seeding pattern WireKit's stateful controls share — it works in plain Blade forms too.

Optimistic UI

Pass the name of the Livewire method the combobox should call and the choice lands immediately, then confirms or undoes itself when the server answers:

<x-wirekit::combobox
    name="country"
    label="Country"
    :value="$country"
    :options="['de' => 'Germany', 'fr' => 'France', 'es' => 'Spain']"
    optimistic="saveCountry"
/>

Load wirekit-optimistic.js alongside whichever bundle you already use — below it, in your layout:

@wirekitScripts
<script src="{{ asset('vendor/wirekit/wirekit-optimistic.js') }}"></script>

Try it

The demo below runs the real path: the change shows immediately, the outline says it is provisional, and the server's answer either confirms it silently or takes it back.

{{-- In your app there is no host: your own Livewire component owns the method. --}}
<x-wirekit::combobox
    name="country"
    label="Country"
    :value="$country"
    :options="['de' => 'Germany', 'fr' => 'France', 'es' => 'Spain']"
    optimistic="saveCountry"
/>

The <livewire:demos.…> wrapper above exists only on this site — it supplies the demo methods so the page can show a real round trip. The block under it is what you write.

The prop takes a method name rather than true because the component cannot know the action otherwise: server actions reach a WireKit component through the attribute bag, so it never sees your wire:click. optimistic replaces wire:model.live here rather than joining it — the method you name is what changes the value on the server; pass the current one with :value so the combobox knows where it started.

All three ways of choosing take the same path: clicking an option, pressing Enter on the highlighted one, and the clear button. Clearing calls your method with null — choosing nothing is still a choice, and the server has to hear about it. Pressing Enter with nothing highlighted sends nothing at all.

After an undo the text field shows the label of the previous selection, not the one that was refused. The field follows the value rather than the click, which is what makes that possible.

Props

Accessibility

• Accessible name (required): give every combobox a name. Use label for a visible label (associated with the input via for), hideLabel to keep that label for screen readers while hiding it visually, or ariaLabel to name the input directly when the surrounding UI already makes its purpose clear (e.g. a compact facet toolbar). Without one, the control fails WCAG 4.1.2.
• Text input: role="combobox", aria-expanded, aria-controls, aria-autocomplete="list"
• Listbox: role="listbox" with unique id linked via aria-controls
• Each option: role="option", aria-selected
• Empty state: "No results" message when filter produces no matches
• Error state: aria-invalid="true" + aria-describedby linking to error message

<x-wirekit::combobox name="country" label="Country" :options="['de' => 'Germany', 'fr' => 'France', 'it' => 'Italy']" placeholder="Search countries…" />

For a compact toolbar where a visible label would crowd the layout, keep the name for assistive tech with ariaLabel:

<x-wirekit::combobox name="specialty" ariaLabel="Filter by specialty" :options="['cardio' => 'Cardiology', 'neuro' => 'Neurology']" placeholder="All specialties" />

Keyboard Interaction

Pitfalls

• Don't use combobox for a known-small option list (≤6 items). A native <x-wirekit::select> is faster, simpler, and screen-reader-friendlier. Comboboxes shine when filtering matters.
• Don't bind wire:model.live on the search input. Every keystroke round-trips. Use the component's built-in client-side filtering and bind wire:model to the selected value only.

Design Tokens

Config Defaults

The defaults live in config/wirekit.php under components.combobox. Override them globally:

'components' => [
    'combobox' => ['size' => 'md', 'placeholder' => 'Type to search...'],
],

Further Reading

• WAI-ARIA 1.2 Combobox Pattern — the authoring pattern this component implements
• MDN: role="combobox"
• MDN: role="listbox"
• MDN: aria-autocomplete
• MDN: aria-expanded