fabioguin / livewire-searchable-select
High-performance Livewire component for searchable select inputs with relevance-based ordering, caching, and optimized UX
Installs: 43
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
pkg:composer/fabioguin/livewire-searchable-select
Requires
- php: ^8.1|^8.2
- illuminate/support: ^10.0|^11.0
- livewire/livewire: ^3.0
Requires (Dev)
- laravel/pint: ^1.16
- orchestra/testbench: ^8.21.0|^9.0
- phpunit/phpunit: ^10.1
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
Property | Arguments | Result | Example |
---|---|---|---|
property | String - required property name | Define the property name | property="country_id" |
model-app | String - required full model name | Define the source of data that will be select | model-app="\App\Models\Country" |
model-app-scope | String - optional name of model sope | Define model scope for filtering results | model-scope-app="isActive" |
option-text | String - required show column on option | Define the column(s) in model that want to be show in select option | option-text="{id} - {name} ({abbreviation})" |
option-value-column | String - required set value | Define the column name as a value data that will be selected | option-value-column="id" |
active-option-text | Mixed - optional set active value text | Define the default selected option to show on select | active-option-text="{{ request()->user()->country_name }}" |
active-option-value | Mixed - optional set active value | Define the default selected option value to pass in the model | active-option-value="{{ request()->user()->country_id }}" |
search-columns | Array - required search column | Define the column in model that want to be searched | :search-columns="['name', 'abbreviation']" |
search-min-chars | Int - optional minimum character | Define minimum character for trigger search event; default: 0 | :search-min-chars="2" |
search-limit-results | Int - optional max results to view in the dropdown | Define the lenght of result for dropdown; default: 10 | :search-limit-results="15" |
input-extra-classes | String - optional add extra classes | Define the extra classes for the input, anyway each element has a class without defined attributes that can be exploited for customization, for example: "select-searchable-input", "select-searchable-input-clear-value", etc. | input-extra-classes="mt-3" |
input-placeholder | String - optional placeholder name | Define the placeholder for select input | input-placeholder="Select country" |
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 toFabioGuin\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/