README

High-performance Livewire component for searchable select inputs with relevance-based ordering, intelligent caching, and optimized UX.

Features

• High Performance: Optimized database queries with intelligent caching
• Relevance-Based Ordering: Smart search results ranked by relevance
• Debounced Input: Smooth UX with 300ms debouncing to reduce server load
• Redis Caching: Automatic caching of search results for better performance
• SQL Injection Protection: Secure input sanitization and validation
• Responsive Design: Works perfectly on all device sizes
• Customizable: Easy to customize with CSS classes and configuration
• Model Scopes: Support for complex model filtering with scopes
• Multi-language: Built-in internationalization support

Requirements

• Laravel 10 or 11
• Livewire 3.0+
• Alpine JS (included with Livewire)
• Redis (optional, for caching)

Installation

You can install the package via composer:

composer require fabioguin/livewire-searchable-select

Redis Configuration (Optional but Recommended)

For optimal performance, configure Redis as your cache driver:

# In your .env file
CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

The package will automatically use Redis for caching search results, significantly improving performance.

Basic Usage

• use trait SearchableSelect in your livewire component:

<?php

namespace App\Http\Livewire\CreateUser;

use Livewire\Component;
use FabioGuin\LivewireSearchableSelect\Traits\SearchableSelect;

class CreateUser extends Component
{
    use SearchableSelect;

    // set properties to get selected value from LivewireSearchableSelect
    public int $country_id;
}

• Use the livewire-searchable-select component in your blade view, and pass in a parameters:

<livewire:select-searchable-input
        property="country_id"
        model-app="\App\Models\Country"
        model-app-scope="isActive"
        option-text="{name}"
        option-value-column="id"
        active-option-text="{{ request()->user()->country_name }}"
        active-option-value="{{ request()->user()->country_id }}"
        :search-columns="['name']"
        :search-min-chars="2"
        :search-limit-results="15"
        input-extra-classes="mt-3"
        input-placeholder="Select country" />

Performance Features

Intelligent Caching

The component automatically caches search results for 5 minutes, dramatically reducing database load:

// Results are automatically cached with intelligent cache keys
// Cache duration: 5 minutes (configurable)
// Cache driver: Uses your configured cache driver (Redis recommended)

Relevance-Based Ordering

Search results are intelligently ordered by relevance:

• Exact match: 100 points
• Starts with: 80 points
• Contains: 60 points
• Ends with: 40 points

Debounced Input

Input is debounced by 300ms to prevent excessive server requests:

<!-- Automatically debounced - no configuration needed -->
<livewire:select-searchable-input ... />

Properties

model-app-scope

With this parameter you can define a query scope of the model to filter the search results in a complex way (see official Laravel documentation). This makes the component even more flexible and usable in multiple contexts. Remember to use a string with the camel case syntax without specifying that it is a "scope" (see example).

Customization

Livewire Select is designed to be easily customizable. You can publish and modify the configuration, views, and language files to suit your needs.

Configuration

You can publish the configuration file with:

php artisan vendor:publish --provider="FabioGuin\LivewireSearchableSelect\LivewireSearchableSelectServiceProvider" --tag="config"

This will publish a livewire-searchable-select.php config file to your config directory. Here you can change the default settings of Livewire Select.

Views

If you need to modify the views, you can publish them with:

php artisan vendor:publish --provider="FabioGuin\LivewireSearchableSelect\LivewireSearchableSelectServiceProvider" --tag="views"

This will publish the view files to resources/views/vendor/livewire-searchable-select. You can edit these files to change the appearance of the select input.

Language

To customize the language strings, you can publish the language files with:

php artisan vendor:publish --provider="FabioGuin\LivewireSearchableSelect\LivewireSearchableSelectServiceProvider" --tag="lang"

This will publish the language files to resources/lang/vendor/livewire-searchable-select. You can edit these files to change the text used by Livewire Select.

What's New in v2.0.0

Major Improvements

• Refactored Architecture: Complete separation of concerns with Config and Service classes
• Security Enhanced: SQL injection protection with input sanitization
• Performance Optimized: Intelligent caching and query optimization
• Smart Ordering: Relevance-based search result ranking
• Better UX: Debounced input for smooth user experience
• Test Coverage: Comprehensive test suite for reliability

Breaking Changes

• Namespace Update: SearchableSelect trait moved to FabioGuin\LivewireSearchableSelect\Traits\SearchableSelect
• Architecture: New Config and Service classes for better maintainability
• Input Handling: Replaced wire:model with debounced Alpine.js input

Migration from v1.x

1. Update Trait Import

// Before (v1.x)
use FabioGuin\LivewireSearchableSelect\SearchableSelect;

// After (v2.0.0)
use FabioGuin\LivewireSearchableSelect\Traits\SearchableSelect;

2. No Other Changes Required

The component API remains the same, so your existing Blade templates will continue to work without modification.

3. Optional: Enable Redis Caching

For better performance, configure Redis as your cache driver (see Installation section above).

Future Developments

The package is actively maintained with the following planned features:

• CSS Framework Support: Tailwind CSS and Bootstrap 4/5 compatibility
• Advanced Analytics: Search analytics and performance metrics
• Real-time Updates: WebSocket support for live updates
• Enhanced i18n: More language support and RTL compatibility
• Mobile Optimization: Touch-friendly mobile interactions
• Advanced Search: Fuzzy search and typo tolerance

Inspired by https://github.com/mitratek/livewire-select

We ❤️ Semantic Versioning https://semver.org/

Open to work, contact me: https://www.linkedin.com/in/fabio-guin-starzero/