Skip to content

No results for

↑ ↓ navigate ↵ open Esc close 
php artisan aura:add combobox

Copies the component source into resources/views/components/aura/. Run php artisan aura:init first if you haven't already. See the CLI guide for all options.

composer require bluestarsystem/aura-ui
php artisan aura:install

Full installation instructions in the Installation guide.

Overview

<x-aura::combobox> is a text field with a list attached: type to narrow it, arrow through the matches, Enter to take one.

The part usually skipped is the announcement. The focus never leaves the input, so the only way to say which option you have arrowed onto is aria-activedescendant — without it the highlight is a colour change and nothing else. This component sets it, points aria-controls at the list, and renders the options as role="option" elements rather than buttons, because a button inside a listbox is in the tab order and Tab walks straight into the popup.

Basic Usage

No matches

<x-aura::combobox
    label="Country"
    placeholder="Start typing..."
    :options="['it' => 'Italy', 'fr' => 'France', 'de' => 'Germany', 'es' => 'Spain']"
/>

Free text

With allow-custom, text that matches nothing becomes the value. Without it, the field goes back to the last option actually chosen when it loses focus — so a half-typed word never submits.

No matches

Type anything, or pick one.

<x-aura::combobox
    label="Tag"
    allow-custom
    hint="Type anything, or pick one."
    :options="['bug' => 'Bug', 'feature' => 'Feature']"
/>

Props

Prop Type Default Description
label string|null null Rendered as a <label for> tied to the field.
options array [] ['value' => 'Label'], or a list of ['value' => …, 'label' => …].
name string|null null Emits a hidden input so the value posts with a plain form.
value string|null null The value selected when the page loads.
allowCustom bool false Whether typed text that matches nothing is a value.
placeholder string|null null Never used as the field's name — that is what label is for.
error string|null null Announced with role="alert" and wired to aria-describedby.
hint string|null null Description text, also wired to aria-describedby.
size string 'md' sm, md, lg.
noResultsText string|null null Defaults to the translated "No matches".

Keyboard

Key Does
Down / Up Moves through the matches, wrapping at both ends.
Enter Takes the highlighted option.
Escape Closes the list, leaving what you typed.
Tab Commits and moves on.

Combobox or Autocomplete?

Autocomplete is for searching a set and picking one of it. Combobox is for a field with a value that also happens to have suggestions — it posts through a hidden input, and it can accept text that is not on the list.