Download the PHP package williamug/searchable-select without Composer

Livewire Searchable Select

A powerful, feature-rich searchable dropdown component for Laravel Livewire 3 & 4 applications. Built with Alpine.js and styled with Tailwind CSS.

Table of Contents

• Features
• Requirements
• Installation
• Tailwind CSS Setup
• Quick Start
• Component Props Reference
• Usage Examples
  • Basic Single Select
  • Multi-Select
  • Dependent/Cascading Dropdowns
  • Grouped Options
  • Custom Keys
  • With Validation
  • Disabled State
  • Without Clear Button
• Advanced Features
• Customization Guide
• Troubleshooting
• Performance Optimization
• Testing
• Demo Application
• Contributing
• License

Features

• Real-time search - Client-side filtering as you type
• Multi-select support - Select multiple options with visual tags/badges
• Grouped options - Organize options into labeled categories
• Clear button - Quickly clear selections
• Dark mode support - Automatically adapts to your theme
• Accessible - Full keyboard navigation and ARIA attributes
• Livewire 3 & 4 compatible - Works seamlessly with both versions
• Responsive - Mobile-friendly and touch-optimized
• Disabled state - Conditional disabling support
• Flexible data - Works with Eloquent models, arrays, collections
• Dependent dropdowns - Perfect for cascading country → region → city selects
• Customizable - Override styles and behavior
• Zero config - Works immediately after installation

Screenshots

Requirements

• PHP: 8.2 or higher
• Laravel: 11.x, 12.x, 13.x
• Livewire: 3.x or 4.x
• Alpine.js: Bundled with Livewire (no separate install needed)
• Tailwind CSS: 3.x or 4.x

Installation

Install the package via Composer:

The package will automatically register its service provider. You're ready to use it immediately!

You can publish the view files if you need to customize the component HTML:

Tailwind CSS Setup

The component is styled with Tailwind utility classes. You must tell Tailwind to scan the package's blade views, otherwise those classes will be purged and the dropdown will appear unstyled or invisible.

Tailwind v4 (@tailwindcss/vite or @tailwindcss/postcss)

Add a @source directive to your main CSS file (typically resources/css/app.css):

Then rebuild your assets:

Tailwind v3 (tailwindcss with tailwind.config.js)

Add the package views to the content array in tailwind.config.js:

Then rebuild your assets:

That's it! The component will use Tailwind classes and support dark mode automatically.

Quick Start

Basic Usage

Step 1: Create a Livewire Component

Step 2: Set up your component class

Step 3: Use the component in your Blade view

That's it! You now have a fully functional searchable dropdown. The component automatically syncs with your Livewire property via wire:model — no extra :selected-value prop needed.

Component Props Reference

Comprehensive list of all available props:

wire:model is a standard Livewire directive, not a declared prop. Pass it as wire:model="propertyName" and the component handles two-way binding automatically.

Props Explanation

Core Props

• options: The data source for your dropdown. Can be:

  • Eloquent Collection: Country::all()
  • Array of objects: [['id' => 1, 'name' => 'USA'], ...]
  • Array of arrays: See above
• wire:model: The Livewire property to bind to. The component uses $wire.entangle() internally to keep the selected value in sync automatically.

Labeling Props

• placeholder: Shows when no option is selected
• searchPlaceholder: Shows in the search input
• emptyMessage: Shows when options array is empty

Data Mapping Props

• optionValue: Which property to use as the value (saved to wire:model)
• optionLabel: Which property to display to users

Example:

Feature Flags

• multiple: Enables multi-select mode with visual tags
• clearable: Shows/hides the × button to clear selection
• disabled: Grays out the component and prevents interaction
• grouped: Enables category headers in the dropdown

Usage Examples

Basic Single Select

The most common use case - a simple searchable dropdown:

Multi-Select

Select multiple options with visual tags/badges:

Selected items show as blue badges with × remove buttons.

Dependent/Cascading Dropdowns

Create related dropdowns where child options depend on parent selections (e.g., Country → Region → City):

Key points:

• Use updatedPropertyName() methods in your Livewire component to react to changes — $wire.set() inside the component triggers these automatically on every selection
• Reset child values when parent changes
• Use :disabled prop to prevent selecting child before parent

Grouped Options

Organize options into labeled categories:

Custom group keys:

If your data structure uses different keys:

Custom Keys

When your data uses different property names:

With Validation

Integrate with Laravel's validation:

Real-time validation:

Disabled State

Conditionally disable the dropdown:

Without Clear Button

Hide the clear (×) button:

Using Arrays Instead of Models

You don't need Eloquent models - plain arrays work too:

Advanced Features

Custom Styling with CSS Classes

Add custom classes to the component wrapper:

Creating Specialized Components

Build reusable components for common patterns:

resources/views/components/country-select.blade.php:

Usage:

Server-Side Search (Large Datasets)

For thousands of records, implement server-side search:

Customization Guide

Publishing Views

If you need to customize the component HTML, publish the view file:

This copies the view to resources/views/vendor/searchable-select/searchable-select.blade.php. Laravel will use your copy instead of the package default.

Dark Mode Support

The component automatically supports dark mode via Tailwind's dark: classes:

Customizing Search Behavior

The component uses client-side filtering by default. To customize:

1. Case sensitivity: Modify the Alpine.js searchTerm filtering logic in the published view
2. Search multiple fields: Adjust the filter to check multiple properties
3. Server-side search: Use the updatedSearchTerm Livewire pattern shown in Advanced Features

Troubleshooting

Common Issues and Solutions

Dropdown doesn't open / Click doesn't work

Causes:

• Alpine.js not loaded
• JavaScript conflicts
• Multiple Alpine.js instances

Solutions:

1. Verify Alpine.js is loaded (it comes with Livewire 3+):

2. Check browser console for JavaScript errors (F12 → Console)

3. Ensure you're not loading Alpine.js separately if using Livewire 3+:

4. Try clearing browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)

Selected value not displaying

Causes:

• Value mismatch between the Livewire property and options
• Wrong optionValue key
• Value not in options array

Solutions:

1. Verify the selected value exists in your options:

2. Check optionValue matches your data structure:

3. Use browser DevTools to inspect the component's Alpine.js data

Styling issues / dropdown appears unstyled or invisible

Causes:

• Package views not included in Tailwind's content scanning
• Tailwind not rebuilt after adding the source
• CSS not loading

Solutions:

1. Add the package views to Tailwind's scan paths and rebuild:

   Tailwind v4 — add a @source line to resources/css/app.css:

   Tailwind v3 — add to the content array in tailwind.config.js:

2. Rebuild Tailwind CSS:

3. Clear Laravel view cache:

4. Check that your CSS is loading in browser DevTools (Network tab)

Options not updating / Stale data

Causes:

• Missing wire:key on components in loops
• Livewire not detecting changes

Solutions:

1. Use wire:key when rendering multiple components in loops:

2. Every selection calls $wire.set() immediately. Ensure your Livewire component has a matching updated{PropertyName}() method if you need to react to the change server-side.

Multi-select not working

Causes:

• Property not defined as array
• Missing :multiple="true"

Solutions:

1. Initialize property as array:

2. Enable multiple mode:

Validation errors not showing

Causes:

• Missing @error directive
• Wrong property name in validation

Solutions:

1. Add error display:

2. Verify property name matches:

Performance issues with large datasets

Causes:

• Too many options loaded at once
• Client-side filtering thousands of items

Solutions:

1. Use Livewire server-side search for large datasets:

2. Select only needed columns:

Performance Optimization

Dataset Size Guidelines

Optimization Techniques

1. Server-Side Search:

2. Caching Options:

3. Select Only Needed Columns:

Testing

The package includes a comprehensive test suite covering all features.

Running Tests

Test Coverage

The package tests include:

• Component rendering
• Single-select functionality
• Multi-select with badges/tags
• Grouped options rendering
• Service provider and component registration
• View namespace resolution

17 tests, 33 assertions - all passing

Demo Application

The package includes a full-featured demo application showcasing all features.

Running the Demo

Visit http://localhost:8000

Note: The demo's composer.json references the local package via a VCS repository pointing to ../. No Packagist fetch needed — it installs directly from the local source.

Demo Features

The demo is a single consolidated page at / showcasing:

• Basic single-select
• Multi-select with badges
• Grouped options
• Preselected values
• Disabled state

Demo Source Code

Check the demo Livewire component in demo/app/Livewire/DemoPage.php for implementation examples.

Frequently Asked Questions

How do I implement country → state → city dropdowns?

See the Dependent/Cascading Dropdowns section for a complete example.

Can I customize the component HTML?

Yes! Publish the view file and edit your copy:

Your copy lands in resources/views/vendor/searchable-select/searchable-select.blade.php.

Does it work with Livewire 3 and 4?

Yes, fully compatible with both Livewire 3.x and 4.x.

How do I search across multiple fields?

Use a Livewire server-side search with a custom query:

Can I pre-select multiple values?

Yes, initialize your property as an array:

Does it support dark mode?

Yes, the component automatically supports dark mode using Tailwind's dark: classes.

How do I disable specific options?

This feature is not built-in, but you can publish the view and add a disabled property check in the options loop.

Can I use it with Inertia.js?

The component is designed for Livewire. For Inertia.js, consider using a Vue/React select component instead.

How do I add icons to options?

Publish the view and customize the option rendering to include icons:

Contributing

We welcome contributions! Here's how to get started:

Development Setup

1. Fork the repository

2. Install dependencies

3. Run tests

Contribution Workflow

1. Create a feature branch

2. Make your changes

   • Add tests for new features
   • Update documentation if needed
   • Follow PSR-12 coding standards

3. Run tests and code style checks

4. Commit your changes

5. Push to your fork

6. Open a Pull Request
   • Describe what your PR does
   • Reference any related issues
   • Ensure all tests pass

Code Style

The project uses:

• Laravel Pint for PHP code formatting
• PSR-12 coding standard
• Pest PHP for testing

Run before committing:

Reporting Bugs

Found a bug? Please open an issue with:

• Laravel version
• Livewire version
• PHP version
• Steps to reproduce
• Expected vs actual behavior

Suggesting Features

Have an idea? Open a feature request describing:

• The use case
• How it would work
• Why it's useful
• Any implementation ideas

Changelog

Please see CHANGELOG for recent changes.

Security

If you discover any security vulnerabilities, please email the maintainer instead of using the issue tracker.

Credits

Author

• William Asaba - GitHub | Twitter

Built With

• Laravel - The PHP Framework
• Livewire - A full-stack framework for Laravel
• Alpine.js - Your new, lightweight, JavaScript framework
• Tailwind CSS - A utility-first CSS framework

Inspiration

Inspired by the need for a simple, searchable select component for Laravel Livewire applications.

License

The MIT License (MIT). Please see License File for more information.

Support the Project

If this package saved you time and effort:

• ⭐ Star the repository on GitHub
• 🐦 Share it on social media
• 🤝 Contribute code or documentation
• 🐛 Report bugs to help improve it
• 💡 Suggest features you'd like to see

Your support helps maintain and improve this package!

Links

• Packagist - Composer package
• GitHub Repository - Source code
• Issue Tracker - Report bugs or request features
• Changelog - Version history
• License - MIT License