• Overview
• Basic Usage
• Props
• Examples
  • Simple String Options
  • Key-Value Options
  • Livewire Server-Side Search
  • Tag Suggestions
  • With Validation Error
• Slots
• Accessibility

Pro Component — This component requires an Aura UI Pro license.

Overview#

The Autocomplete component provides a text input with a dynamic dropdown of filtered suggestions. It supports both static option arrays and server-side search via Livewire integration. As the user types, matching results appear in a dropdown, allowing quick selection. Built with Alpine.js for instant client-side filtering and optional debounced server-side requests.

Basic Usage#

<x-aura::autocomplete
    label="Country"
    name="country"
    :options="['Italy', 'Germany', 'France', 'Spain', 'Portugal']"
    placeholder="Search for a country..."
/>

Props#

Examples#

Simple String Options#

<x-aura::autocomplete
    label="Fruit"
    name="fruit"
    :options="['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape']"
    placeholder="Type to search fruits..."
    :minChars="2"
/>

Key-Value Options#

<x-aura::autocomplete
    label="Assign User"
    name="user_id"
    :options="[
        ['value' => 1, 'label' => 'Alice Johnson'],
        ['value' => 2, 'label' => 'Bob Smith'],
        ['value' => 3, 'label' => 'Charlie Brown'],
        ['value' => 4, 'label' => 'Diana Prince'],
    ]"
    placeholder="Search users..."
/>

Livewire Server-Side Search#

For large datasets, use Livewire to fetch results from the server. Bind the input with wire:model.live.debounce.300ms and update the options dynamically.

<!-- In your Livewire component Blade view -->
<x-aura::autocomplete
    label="Customer"
    name="customer_id"
    :options="$customerResults"
    placeholder="Search customers by name or email..."
    :minChars="3"
    wire:model.live.debounce.300ms="customerSearch"
    :error="$errors->first('customer_id')"
/>

// In your Livewire component class
use Livewire\Component;

class OrderForm extends Component
{
    public string $customerSearch = '';
    public array $customerResults = [];
    public ?int $customer_id = null;

    public function updatedCustomerSearch(string $value): void
    {
        if (strlen($value) < 3) {
            $this->customerResults = [];
            return;
        }

        $this->customerResults = Customer::query()
            ->where('name', 'like', "%{$value}%")
            ->orWhere('email', 'like', "%{$value}%")
            ->limit(10)
            ->get()
            ->map(fn ($c) => ['value' => $c->id, 'label' => "{$c->name} ({$c->email})"])
            ->toArray();
    }
}

Tag Suggestions#

<x-aura::autocomplete
    label="Add Tag"
    name="tag"
    :options="$availableTags"
    placeholder="Search or create a tag..."
    :minChars="1"
/>

With Validation Error#

<x-aura::autocomplete
    label="Category"
    name="category_id"
    :options="$categories"
    placeholder="Select a category..."
    :error="$errors->first('category_id')"
/>

Slots#

The dropdown list is rendered automatically based on the options prop. Each option displays the label (or string value) and submits the corresponding value when selected.

Accessibility#

• The input has role="combobox" with aria-autocomplete="list".
• The dropdown list uses role="listbox" with each option as role="option".
• aria-expanded indicates whether the dropdown is visible.
• aria-activedescendant tracks the currently highlighted option.
• Arrow Up/Down navigate through the suggestion list.
• Enter selects the highlighted option.
• Escape closes the dropdown without selecting.
• The component associates the label with the input via for/id attributes.