A visual guide to navigate the complete documentation.
┌─────────────────────────────────────────────────────────────────┐
│ SEARCHABLE SELECT PACKAGE │
│ Laravel Livewire Dropdown Component │
└─────────────────────────────────────────────────────────────────┘
PACKAGE STRUCTURE
├── README.md (1,723 lines) ─────────► Main documentation
├── DOCUMENTATION.md ────────────────► Documentation overview
├── CHANGELOG.md ────────────────────► Version history
├── tests/ ──────────────────────────► 24 tests (46 assertions)
├── resources/views/
│ ├── searchable-select.blade.php ───► Tailwind version
│ └── searchable-select-bootstrap.blade.php ─► Bootstrap version
├── config/
│ └── searchable-select.php ─────────► Theme configuration
└── demo/ ───────────────────────────► Live demo app
════════════════════════════════════════════════════════════════
MAIN DOCUMENTATION SECTIONS (README.md)
┌───────────────────────────────────────────────────────────────┐
│ 1. INTRODUCTION (Lines 1-100) │
├───────────────────────────────────────────────────────────────┤
│ • Package overview & badges │
│ • Feature list (16 features) │
│ • Screenshots │
│ • Requirements & compatibility │
│ • Table of contents │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 2. INSTALLATION & SETUP (Lines 101-370) │
├───────────────────────────────────────────────────────────────┤
│ ✓ Composer installation │
│ ✓ Tailwind CSS setup │
│ ✓ Bootstrap 5 setup │
│ ✓ Theme switching │
│ ✓ Environment configuration │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 3. QUICK START (Lines 371-470) │
├───────────────────────────────────────────────────────────────┤
│ Step 1: Create Livewire component │
│ Step 2: Set up component class │
│ Step 3: Use in Blade view │
│ ⚡ Get started in 5 minutes! │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 4. COMPONENT PROPS (Lines 471-620) │
├───────────────────────────────────────────────────────────────┤
│ Complete reference table │
│ 17 props documented │
│ Detailed explanations │
│ Usage examples │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 5. USAGE EXAMPLES (Lines 621-1100) │
├───────────────────────────────────────────────────────────────┤
│ • Basic Single Select │
│ • Multi-Select with badges │
│ • Dependent/Cascading Dropdowns │
│ • Grouped Options │
│ • API/Ajax Integration │
│ • Custom Keys │
│ • With Validation │
│ • Disabled State │
│ • Without Clear Button │
│ • Using Arrays │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 6. ADVANCED FEATURES (Lines 1101-1250) │
├───────────────────────────────────────────────────────────────┤
│ Custom CSS styling │
│ Creating specialized components │
│ Server-side search │
│ Mixing themes │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 7. CUSTOMIZATION (Lines 1251-1330) │
├───────────────────────────────────────────────────────────────┤
│ • Publishing views │
│ • Dark mode support │
│ • Custom search behavior │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 8. TROUBLESHOOTING (Lines 1331-1560) │
├───────────────────────────────────────────────────────────────┤
│ Dropdown doesn't open │
│ Selected value not displaying │
│ Styling issues (Tailwind) │
│ Styling issues (Bootstrap) │
│ Options not updating │
│ API integration problems │
│ Multi-select not working │
│ Validation errors │
│ Performance issues │
│ │
│ Each issue includes: │
│ Causes │
│ ✓ Solutions with code │
│ ✓ Debugging steps │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 9. PERFORMANCE (Lines 1561-1640) │
├───────────────────────────────────────────────────────────────┤
│ Dataset Guidelines: │
│ • < 100 items → Client-side ✅ │
│ • 100-1,000 → Client-side ✅ │
│ • 1,000-10,000 → Consider API ⚠️ │
│ • > 10,000 → Must use API ❗ │
│ │
│ Optimization Techniques: │
│ • Lazy loading │
│ • Server-side search │
│ • Caching │
│ • Column selection │
│ • Debouncing │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 10. TESTING & DEMO (Lines 1641-1710) │
├───────────────────────────────────────────────────────────────┤
│ 🧪 Test suite: 24 tests, 46 assertions │
│ 🚀 Demo app: 7 live examples │
│ 📦 Docker support │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 11. FAQ (Lines 1711-1830) │
├───────────────────────────────────────────────────────────────┤
│ ❓ Can I mix Tailwind & Bootstrap? │
│ ❓ How to implement cascading dropdowns? │
│ ❓ Can I customize HTML? │
│ ❓ Livewire 3 & 4 compatible? │
│ ❓ Search multiple fields? │
│ ❓ Pre-select values? │
│ ❓ Dark mode support? │
│ + 3 more questions answered │
└───────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────┐
│ 12. CONTRIBUTING (Lines 1831-1920) │
├───────────────────────────────────────────────────────────────┤
│ • Development setup │
│ • Contribution workflow │
│ • Code style (PSR-12) │
│ • Bug reporting │
│ • Feature requests │
└───────────────────────────────────────────────────────────────┘
════════════════════════════════════════════════════════════════
🎯 QUICK REFERENCE GUIDE
┌─────────────────────────────────────────────────────────────┐
│ I WANT TO... GO TO SECTION │
├─────────────────────────────────────────────────────────────┤
│ Install the package Installation │
│ Set up Tailwind CSS Tailwind CSS Setup │
│ Set up Bootstrap 5 Bootstrap 5 Setup │
│ Create my first dropdown Quick Start │
│ See all available props Component Props │
│ Learn by example Usage Examples │
│ Fix dropdown issues Troubleshooting │
│ Optimize for large datasets Performance │
│ Create cascading dropdowns Cascading Dropdowns │
│ Fetch data from API API Integration │
│ Enable multi-select Multi-Select │
│ Customize the HTML Customization │
│ Run the demo Demo Application │
│ Report a bug Contributing │
└─────────────────────────────────────────────────────────────┘
════════════════════════════════════════════════════════════════
🎨 THEME CONFIGURATION
┌─────────────────────────────────────────────────────────────┐
│ TAILWIND CSS (Default) │
├─────────────────────────────────────────────────────────────┤
│ • Automatic dark mode │
│ • Utility-first classes │
│ • Purge configuration needed │
│ • Rebuild on changes: npm run build │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ BOOTSTRAP 5 │
├─────────────────────────────────────────────────────────────┤
│ 1. Publish config: php artisan vendor:publish │
│ 2. Set theme: 'theme' => 'bootstrap' │
│ 3. Load Bootstrap CSS in layout │
│ 4. Clear cache: php artisan config:clear │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ PER-COMPONENT OVERRIDE │
├─────────────────────────────────────────────────────────────┤
│ <x-searchable-select theme="tailwind" /> │
│ <x-searchable-select theme="bootstrap" /> │
└─────────────────────────────────────────────────────────────┘
════════════════════════════════════════════════════════════════
🚀 USAGE PATTERNS
Pattern 1: Basic Select
───────────────────────
<x-searchable-select
:options="$countries"
wire-model="country_id"
:selected-value="$country_id"
/>
Pattern 2: Multi-Select
───────────────────────
<x-searchable-select
:options="$skills"
wire-model="selected_skills"
:selected-value="$selected_skills"
:multiple="true"
/>
Pattern 3: API Integration
──────────────────────────
<x-searchable-select
api-url="/api/users/search"
:options="[]"
wire-model="user_id"
/>
Pattern 4: Cascading
────────────────────
<x-searchable-select
wire-model.live="country_id"
:options="$countries"
/>
<x-searchable-select
wire-model="city_id"
:options="$cities"
:disabled="!$country_id"
/>
Pattern 5: Grouped Options
──────────────────────────
<x-searchable-select
:options="$grouped_data"
:grouped="true"
wire-model="selection"
/>
════════════════════════════════════════════════════════════════
🔧 COMMON COMMANDS
Install package:
$ composer require williamug/searchable-select
Publish config:
$ php artisan vendor:publish --tag=searchable-select-config
Publish views:
$ php artisan vendor:publish --tag=searchable-select-views
Run tests:
$ composer test
Clear caches:
$ php artisan config:clear
$ php artisan view:clear
Run demo:
$ cd demo && php artisan serve
════════════════════════════════════════════════════════════════
📊 DOCUMENTATION STATS
Total Lines: 1,723
Code Examples: 50+
Features Documented: 16
Props Documented: 17
Troubleshooting Items: 10+
Usage Examples: 10
Tests: 24 (46 assertions)
Themes Supported: 2 (Tailwind, Bootstrap)
════════════════════════════════════════════════════════════════
💡 PRO TIPS
1. Always pass :selected-value for reactivity
2. Use wire:key in loops
3. API integration for > 1,000 options
4. Debounce dependent dropdowns (300ms)
5. Cache static data (countries, etc.)
6. Select only needed columns
7. Use wire-model.live for instant updates
8. Clear caches after config changes
════════════════════════════════════════════════════════════════
📞 SUPPORT & LINKS
Documentation: README.md
Package: packagist.org/packages/williamug/searchable-select
Repository: github.com/williamug/searchable-select
Issues: github.com/williamug/searchable-select/issues
Demo: demo/README.md
Tests: composer test
════════════════════════════════════════════════════════════════
Made with ❤️ for the Laravel community
For complete documentation, see README.md (1,723 lines)