Laravel Simple Select Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require victorybiz/laravel-simple-select
   npm install --save-dev @popperjs/core
   npm install --save @popperjs/core
   

   Publish assets:

   php artisan vendor:publish --tag=simple-select-assets
   

   Add to resources/js/app.js:

   import 'laravel-simple-select';
   

2. First Blade Usage:

   <x-simple-select wire:model="selectedValue" :options="$options" />
   

   Ensure Livewire is set up if using wire:model.

3. First Livewire Usage:

   use Victorybiz\SimpleSelect\Livewire\SimpleSelect;
   
   public $selectedValue;
   public $options = ['Option 1', 'Option 2', 'Option 3'];
   

   Blade:

   <livewire:simple-select wire:model="selectedValue" :options="$options" />
   

Implementation Patterns

Blade Integration

• Basic Select:

  <x-simple-select
      name="category"
      :options="$categories"
      placeholder="Select a category"
      wire:model="categoryId"
  />
  

• Custom Display Logic: Use slots for dynamic rendering:

  <x-simple-select :options="$users">
      <x-slot name="option">
          {{ $user->name }} ({{ $user->email }})
      </x-slot>
  </x-simple-select>
  

Livewire Workflow

1. Component Setup:

   public $selectedId;
   public $options = [];
   
   public function mount() {
       $this->options = User::pluck('name', 'id')->toArray();
   }
   

2. Dynamic Updates:

   public function updatedSelectedId($value) {
       $this->validate(['selectedId' => 'required']);
       // Handle selection change
   }
   

Dependent Selects

• Cascading Selects:

  <x-simple-select
      wire:model="countryId"
      :options="$countries"
      @change="updateCities"
  />
  <x-simple-select
      wire:model="cityId"
      :options="$cities"
  />
  

  Livewire:

  public function updateCities($countryId) {
      $this->cities = City::where('country_id', $countryId)->pluck('name', 'id');
  }
  

Event Handling

• Custom Events:

  <x-simple-select
      @selected="handleSelection"
      :options="$options"
  />
  

  JavaScript:

  document.addEventListener('selected', (e) => {
      console.log('Selected:', e.detail.value);
  });
  

Gotchas and Tips

Common Pitfalls

1. Missing JavaScript Dependencies:

   • Ensure @popperjs/core is installed and imported. Forgetting this causes dropdown positioning issues.

2. Livewire Model Binding:

   • If wire:model isn’t updating, verify the property name matches exactly (case-sensitive) and the component is properly registered.

3. Slot Scope Confusion:

   • Blade slots like option or selected receive the current item as $item. Misusing $option or $selected will fail silently.

4. Dynamic Options:

   • Avoid passing raw Eloquent collections directly. Use pluck() or toArray() to prevent memory leaks:

     // Bad:
     :options="$users"
     // Good:
     :options="$users->pluck('name', 'id')"
     

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify the component renders correctly. Check for missing classes or attributes.

• Check Console for Errors: Simple Select logs errors to the console. Look for Uncaught TypeError or SimpleSelect not defined.

• Disable Caching: If changes aren’t reflecting, clear Livewire and Blade caches:

  php artisan view:clear
  php artisan cache:clear
  

Performance Optimization

• Lazy Loading: For large datasets, fetch options on demand:

  public function updatedSearch($search) {
      $this->options = User::where('name', 'like', "%{$search}%")
          ->limit(100)
          ->pluck('name', 'id');
  }
  

• Debounce Search: Add a debounce to avoid excessive API calls:

  document.addEventListener('input', (e) => {
      if (e.target.classList.contains('simple-select-search')) {
          clearTimeout(window.searchTimeout);
          window.searchTimeout = setTimeout(() => {
              // Trigger search
          }, 300);
      }
  });
  

Extension Points

1. Custom Templates: Override the default template by publishing and modifying:

   php artisan vendor:publish --tag=simple-select-views
   

   Edit resources/views/vendor/simple-select/select.blade.php.

2. Add Icons: Use the icon slot for custom icons:

   <x-simple-select :options="$options">
       <x-slot name="icon">
           <i class="fas fa-search"></i>
       </x-slot>
   </x-simple-select>
   

3. Accessibility: Add aria-label or aria-describedby for screen readers:

   <x-simple-select
       aria-label="Select a user"
       :options="$users"
   />
   

4. Styling: Use Tailwind or custom CSS. Key classes:

   • .simple-select-dropdown (dropdown container)
   • .simple-select-option (option items)
   • .simple-select-selected (selected item).