amabk/livewire-search-select

Livewire Search Select

A powerful and customizable Livewire component for searchable select dropdowns. Supports multi-field labels, concatenation, and emits Livewire events for reactive parent handling.

Usage

1. Installation

Install via Composer:

composer require amabk/livewire-search-select

2. Basic Usage

Add the component to any Blade view:

Single-select

<livewire:search-select
    model-class="\App\Models\User"
    :label-fields="['name','email']"
    :search-fields="['name','email']"
    :concat-fields="true"
    placeholder="Search by name or email…"
    emit-event="userSelected"
    :selected-id="$userId ?? null"
    :initial-load="5"
    input-class="border-gray-300 rounded-md shadow-sm focus-within:ring-1 focus-within:ring-blue-500 focus-within:border-blue-500"
/>

Multi-select (chips inside field)

<livewire:search-select
    model-class="\App\Models\User"
    :label-fields="['name','email']"
    :search-fields="['name','email']"
    :concat-fields="true"
    :multiple="true"
    :selected-ids="$preselected ?? []"
    :initial-load="8"
    placeholder="Search and add users…"
    input-class="border-gray-300 rounded-md shadow-sm focus-within:ring-1 focus-within:ring-blue-500 focus-within:border-blue-500"
/>

Custom separators

{{-- Display label uses " | ", search concatenation still uses space (more forgiving) --}}
<livewire:search-select
  model-class="\App\Models\User"
  :label-fields="['name','email']"
  :search-fields="['name','email']"
  :concat-fields="true"
  label-separator=" | "
  search-separator=" "
/>

{{-- Both label and search use the same separator --}}
<livewire:search-select
  model-class="\App\Models\User"
  :label-fields="['first_name','last_name','email']"
  :search-fields="['first_name','last_name','email']"
  :concat-fields="true"
  label-separator=" · "
  search-separator=" · "
/>

3. Listening for Selection Events

When a user selects an option, the component emits a Livewire event (named by your emit-event prop) to the parent component. You can listen for it and update your parent Livewire component’s data accordingly.

Example Parent Component:

class UserForm extends Component
{
    public $selectedUserIds = [];

    #[On('usersSelected')] 
    // single: receives id or '' when cleared
    // multi: receives array<int> of ids
    public function usersSelected($userIds)
    {
        $this->selectedUserIds = $userIds;
    }

    public function render()
    {
        return view('livewire.user-form');
    }
}

In your Blade view:

<livewire:search-select
    :model-class="\App\Models\User::class"
    label-fields="name,email"
    label-separator=" ["
    label-suffix="]"
    :multiple="true"
    emit-event="usersSelected"
/>
Selected User IDs: {{ implode(', ', $selectedUserIds) }}

4. Customizing Appearance

You can pass custom CSS classes to the input and the options list:

<livewire:search-select
    :model-class="\App\Models\Product::class"
    :label-fields="['title', 'sku']"
    label-separator=" | SKU: "
    :multiple="true"
    emit-event="productsChosen"
    input-class="border-blue-500"
    option-class="max-h-48"
    placeholder="Find a product..."
/>

5. Setting a Default Selected Option

To set a default selection:

<livewire:search-select
    :model-class="\App\Models\Category::class"
    label-fields="name"
    :selected-id="[5, 9]"
    :multiple="true"
    emit-event="categoriesChosen"
/>

This will preselect the items with id = 5 and id = 9 and show their labels in the input.

6. Troubleshooting & Tips

• No results found: Ensure your model and label fields are correct and records exist.
• Alpine/Livewire conflicts: Alpine.js is auto-reinitialized after Livewire updates, but if you experience issues, check your Alpine.js version.
• Emitted event not caught? Ensure your parent Livewire component is listening for the same event name as the emit-event you specify.

7. Development

• PSR-4 namespace: AMABK\LivewireSearchSelect\ → src/
• Component class: AMABK\LivewireSearchSelect\SearchSelect
• View: resources/views/search-select.blade.php (Loaded as view('livewire-search-select::search-select'))

8. Example: User Dropdown in a Form

<form wire:submit.prevent="save">
    <livewire:search-select
        :model-class="\App\Models\User::class"
        :label-fields="['name', 'email']"
        :search-fields="['name', 'email', 'address']"
        label-separator=", "
        label-suffix=" (active)"
        :multiple="true"
        emit-event="userSelected"
        placeholder="Search for a user by name or email..."
    />

    <button type="submit" class="btn btn-primary">Submit</button>
</form>

// Parent Component (UserForm.php)
public $userIds = [];
protected $listeners = ['userSelected'];

public function userSelected($userIds)
{
    $this->userIds = $userIds;
}

10. Advanced: Use With Any Model & Any Label Format

<livewire:search-select
    :model-class="\App\Models\Country::class"
    :label-fields="['country_name', 'country_code']"
    :search-fields="['name', 'currency_code']"
    label-separator=" - "
    label-suffix=""
    :multiple="true"
    emit-event="countriesSelected"
    placeholder="Search country..."
/>

For advanced use, extend the component in your own package. For issues, open a GitHub issue or PR!

License

MIT © AMABK