Combobox

Searchable dropdown component for single selection with Livewire integration.

Usage

<x-combobox
    :options="$options"
    wire:model="selectedValue"
    label="Select an option"
/>

With Images and Secondary Display

Display images and secondary text alongside options:

<x-combobox
    id="selectedTranslationLanguage"
    wire:model.live="selectedTranslationLanguage"
    wire:target="createTranslationWithAi, createManualTranslation"
    :options="$formattedOptions"
    imageKey="flag"
    displayKey="label"
    secondaryDisplayKey="localName"
    valueKey="value"
    :placeholder="__('Select a language')"
/>

Multi-Select Combobox

Allow users to select multiple options from a searchable dropdown list.

Usage

<x-combobox-multiselect
    :options="$options"
    wire:model="selectedValues"
    label="Select categories"
    :placeholder="__('Select categories')"
/>

Example with Categories

<x-combobox-multiselect
    id="categories"
    name="categories"
    wire:model="categories"
    :options="$this->options"
    :label="__('Categories')"
    :placeholder="__('Select categories')"
    emptyStateMessage="No categories available"
    displayKey="label"
    valueKey="value"
/>

Phone Combobox

Combined country code selector with phone number input field.

Usage

<x-combobox-phone
    wire:model="phoneNumber"
    label="Phone Number"
    defaultCountry="us"
/>

Options Format

Options should be formatted as arrays with value, label, and optional keys:

$formattedOptions = [
    [
        'value' => 'en',
        'label' => 'English',
        'localName' => 'English',
        'flag' => 'https://flagcdn.com/gb.svg',
    ],
    [
        'value' => 'fr',
        'label' => 'French',
        'localName' => 'Français',
        'flag' => 'https://flagcdn.com/fr.svg',
    ],
];

Livewire Integration

The combobox supports all Livewire model modifiers:

• wire:model - Deferred updates
• wire:model.live - Real-time updates
• wire:model.defer - Explicit deferred

Use wire:target to specify which actions should show loading states:

<x-combobox
    wire:model.live="selectedValue"
    wire:target="save, update"
    :options="$options"
/>

Props Reference

Combobox Props

Prop	Type	Default	Description
options	array	[]	Array of option objects
wire:model	string	-	Livewire property to bind (supports .live, .defer, etc.)
displayKey	string	label	Key for primary display text
secondaryDisplayKey	string|null	null	Key for secondary display text (shown in parentheses)
valueKey	string	value	Key for the option value
imageKey	string|null	null	Key for image URL to display with options
placeholder	string|null	Please select	Placeholder text when no option is selected
label	string|null	null	Label text displayed above the combobox
searchable	bool	true	Enable search functionality
disabled	bool	false	Disable the combobox

Multi-Select Combobox Props

Multi-select combobox supports all standard combobox props, plus:

Prop	Type	Default	Description
selectedValues	array	[]	Initial selected values (array of option values)
emptyStateMessage	string|null	No options available	Message displayed when no options are available

Note: The wire:model property should be bound to an array. Selected values are stored as an array of option values.

Phone Combobox Props

Prop	Type	Default	Description
wire:model	string	-	Livewire property to bind the phone number
defaultCountry	string	us	ISO code of the default country (e.g., 'us', 'gb', 'fr')
placeholder	string	+00 000-000-0000	Placeholder for the phone number input
label	string	Phone Number	Label text displayed above the input
disabled	bool	false	Disable the phone input

References

Category	Path / Name	Description
Component	resources/views/components/combobox.blade.php	Single-select combobox
Component	resources/views/components/combobox-multiselect.blade.php	Multi-select combobox
Component	resources/views/components/combobox-phone.blade.php	Phone number input with country selector

For the detailed documentation, please visit the Penguin UI Combobox.