Download the PHP package ajjitech/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 supports both Tailwind CSS and Bootstrap 5 out of the box!

Table of Contents

• Features
• Requirements
• Installation
• CSS Framework Setup
  • Tailwind CSS (Default)
  • Bootstrap 5
  • Switching Themes
• Quick Start
• Component Props Reference
• Usage Examples
  • Basic Single Select
  • Multi-Select
  • Dependent/Cascading Dropdowns
  • Grouped Options
  • API/Ajax Integration
  • 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
• Ajax/API integration - Fetch options dynamically from REST endpoints
• Grouped options - Organize options into labeled categories
• Clear button - Quickly clear selections
• Dark mode support - Automatically adapts to your theme (Tailwind)
• 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
• Multiple CSS frameworks - Full support for Tailwind CSS and Bootstrap 5
• Per-component theme override - Mix frameworks in the same app
• Customizable - Override styles and behavior
• Zero config - Works immediately after installation

Screenshots

Requirements

• PHP: 8.1 or higher
• Laravel: 9.x, 10.x, 11.x, or 12.x
• Livewire: 3.x or 4.x
• Alpine.js: Bundled with Livewire (no separate install needed)
• CSS Framework (choose one):
  • Tailwind CSS 3.x+ (default)
  • Bootstrap 5.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 configuration file:

CSS Framework Setup

Tailwind CSS (Default)

The component uses Tailwind CSS by default. No additional configuration needed!

1. Ensure Tailwind is installed in your project:

2. Add the package views to your tailwind.config.js:

3. Build your CSS:

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

Bootstrap 5

To use Bootstrap 5 instead of Tailwind:

1. Publish the configuration file:

This creates config/searchable-select.php.

2. Set the theme to Bootstrap:

Edit config/searchable-select.php:

Or use environment variable (recommended):

Add to your .env file:

3. Include Bootstrap assets in your layout if you haven't already:

Add to your resources/views/layouts/app.blade.php (or wherever your layout is):

Note: The component's dropdown functionality uses Alpine.js (included with Livewire), so Bootstrap's JavaScript is optional unless you're using other Bootstrap components.

Switching Themes

Global Theme Switch

Change the theme application-wide by updating config/searchable-select.php:

Or via environment variable:

Per-Component Theme Override

You can override the theme for individual components using the theme prop:

This allows you to:

• Gradually migrate from one framework to another
• Mix frameworks in the same application
• Use different themes for different sections of your app

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.

Component Props Reference

Comprehensive list of all available props:

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

• wireModel: The Livewire property name to bind. Use wire-model (kebab-case) in Blade.

• selectedValue: Pass the current value to keep the component in sync. Essential for reactive updates.

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

API Integration Props

• apiUrl: Backend endpoint that returns JSON with options
• apiSearchParam: The query parameter for search term

See API/Ajax Integration for full examples.

Theme Props

• theme: Override the global theme setting for this specific component

Usage Examples

Basic Single Select

The most common use case - a simple searchable dropdown:

Multi-Select

Select multiple options with visual tags/badges:

Tailwind styling: Selected items show as blue badges with × remove buttons Bootstrap styling: Selected items show as primary 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 wire-model.live on parent dropdowns to trigger updates immediately
• Use updatedPropertyName() methods to react to changes
• 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:

API/Ajax Integration

Fetch options dynamically from a backend API:

Step 1: Create an API endpoint

Step 2: Use the component with API URL

Multi-select with API:

API Response Format:

Your API should return JSON in this format:

For custom keys, use option-value and option-label:

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:

Tailwind:

Bootstrap:

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:

Or better yet, use the built-in API integration feature shown above.

Mixing Themes in One Application

You can use both Tailwind and Bootstrap in the same app:

Customization Guide

Publishing Views

If you need to customize the component HTML:

This copies the views to resources/views/vendor/searchable-select/:

• searchable-select.blade.php - Tailwind version
• searchable-select-bootstrap.blade.php - Bootstrap version

Now you can modify them as needed. Your custom views will be used instead of the package defaults.

Dark Mode Support (Tailwind)

The Tailwind version automatically supports dark mode:

Bootstrap Dark Mode

For Bootstrap dark mode, you can:

1. Use Bootstrap's data-bs-theme attribute:

2. Or publish the Bootstrap view and customize the color classes

Customizing Search Behavior

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

1. Case sensitivity: Modify the Alpine.js searchTerm filtering logic
2. Search multiple fields: Adjust the filter to check multiple properties
3. Server-side search: Use wire-model.live.debounce with API integration

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 selectedValue 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 (Tailwind)

Causes:

• Package views not included in Tailwind purge paths
• Tailwind not built
• CSS not loading

Solutions:

1. Add package views to tailwind.config.js:

2. Rebuild Tailwind CSS:

3. Clear Laravel view cache:

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

Styling issues (Bootstrap)

Causes:

• Bootstrap CSS not loaded
• Wrong theme configuration
• CSS conflicts

Solutions:

1. Verify Bootstrap is loaded in your layout:

2. Confirm theme is set to Bootstrap:

3. Clear config cache:

4. Use browser DevTools to inspect if correct classes are applied (should see form-control, dropdown-menu, etc.)

Options not updating / Stale data

Causes:

• Missing wire:key on components
• Not using selectedValue prop
• Livewire not detecting changes

Solutions:

1. Always pass :selected-value for reactivity:

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

3. Use wire-model.live for immediate updates:

API integration not working

Causes:

• Wrong API URL
• CORS issues
• Wrong response format

Solutions:

1. Verify API endpoint is accessible:

2. Check API response format (must have data key):

3. Check browser Network tab (F12) for API requests and responses

4. For CORS issues, add to config/cors.php:

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 API integration for large datasets:

2. Implement server-side pagination:

3. Use debouncing for search:

Performance Optimization

Dataset Size Guidelines

Optimization Techniques

1. Lazy Loading with API:

2. Server-Side Search:

3. Caching Options:

4. Select Only Needed Columns:

5. Debouncing for Dependent Dropdowns:

Testing

The package includes a comprehensive test suite covering all features.

Running Tests

Test Coverage

The package tests include:

• Component rendering (Tailwind & Bootstrap)
• Single-select functionality
• Multi-select with badges/tags
• Grouped options rendering
• Theme switching and overrides
• Service provider registration
• Configuration loading
• Install command

24 tests, 46 assertions - all passing

Demo Application

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

Running the Demo

With Docker:

Visit http://localhost:8000

Without Docker:

Demo Features

The demo includes live examples of:

• Basic single-select - /
• Multi-select mode - /multi-select
• Grouped options - /grouped
• API integration - /api-demo
• Dependent dropdowns - /cascading
• Bootstrap theme - /bootstrap
• All features combined - /advanced

Demo Source Code

Check the demo Livewire components in demo/app/Livewire/ for implementation examples.

Frequently Asked Questions

Can I use both Tailwind and Bootstrap in the same project?

Yes! You can set different themes per component:

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 views:

Then edit the files in resources/views/vendor/searchable-select/.

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 API integration with a custom endpoint that searches multiple columns:

Can I pre-select multiple values?

Yes, initialize your property as an array:

Does it support dark mode?

Yes, the Tailwind version automatically supports dark mode using dark: classes. For Bootstrap, use Bootstrap 5.3's dark mode features.

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
• CSS framework (Tailwind/Bootstrap)
• 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
• Bootstrap - The most popular HTML, CSS, and JS library

Inspiration

Inspired by the need for a simple, framework-agnostic 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