README

Powerful searchable select components with multi-select and drag-ordering support for Laravel Livewire & Alpine.js.

Features

• Single & Multi-select variants - Choose between single selection or multiple selections with chips
• Searchable/filterable options - Built-in search functionality for large option lists
• Drag & drop reordering - Reorder selected items in multi-select mode
• Dark mode support - Full support for dark mode styling
• Full Livewire integration - Seamless wire:model binding with defer support
• Zero JavaScript compilation - Uses Livewire's bundled Alpine.js
• TailwindCSS styled - Fully customizable with TailwindCSS
• Flexible options format - Supports arrays, objects, or mixed formats

Requirements

• PHP ^8.2
• Laravel ^11.0 or ^12.0
• Livewire ^3.0
• TailwindCSS ^3.0 or ^4.0

Installation

Step 1: Install via Composer

composer require uluumbch/alpine-select-livewire

Step 2: Configure TailwindCSS

Add the package views to your TailwindCSS content configuration.

For TailwindCSS v3 (tailwind.config.js):

export default {
  content: [
    './resources/**/*.blade.php',
    './vendor/uluumbch/alpine-select-livewire/resources/**/*.blade.php',
  ],
  // ... rest of config
}

For TailwindCSS v4 (resources/css/app.css):

@import 'tailwindcss';

@source '../views';
@source '../../vendor/uluumbch/alpine-select-livewire/resources';

Step 3: Rebuild Assets

npm run build

The service provider will be automatically registered via Laravel's package discovery.

Usage

Single Select

Basic single-select dropdown:

<x-alpine-select::default
    wire:model="selectedOption"
    :options="['Option 1', 'Option 2', 'Option 3']"
    placeholder="Choose an option..."
/>

With object options (value/label):

<x-alpine-select::default
    wire:model="religion"
    :options="[
        ['value' => 'islam', 'label' => 'Islam'],
        ['value' => 'christian', 'label' => 'Christian'],
        ['value' => 'catholic', 'label' => 'Catholic'],
    ]"
    placeholder="Select religion..."
    searchable
    clearable
/>

Multi Select

Basic multi-select with chips:

<x-alpine-select::multiple
    wire:model="selectedItems"
    :options="[
        ['value' => 1, 'label' => 'Option 1'],
        ['value' => 2, 'label' => 'Option 2'],
        ['value' => 3, 'label' => 'Option 3'],
    ]"
    placeholder="Select multiple..."
/>

With drag-and-drop ordering:

<x-alpine-select::multiple
    wire:model="stages"
    :options="$stageOptions"
    :selected="$stages"
    placeholder="Select stages..."
    searchable
    clearable
    orderable
/>

Component API

Single Select (<x-alpine-select::default>)

Multi Select (<x-alpine-select::multiple>)

Options Format

The package intelligently normalizes options into a consistent format. You can pass options in various formats:

Simple Array

$options = ['Option 1', 'Option 2', 'Option 3'];

Value/Label Objects

$options = [
    ['value' => 1, 'label' => 'First Option'],
    ['value' => 2, 'label' => 'Second Option'],
];

Alternative Object Keys

The package also recognizes these alternative keys:

• id, key (as value)
• nama, text (as label)

$options = [
    ['id' => 1, 'nama' => 'Jakarta'],
    ['id' => 2, 'nama' => 'Surabaya'],
];

Livewire Integration

Wire Model Binding

The component supports all Livewire wire:model modifiers:

{{-- Immediate sync --}}
<x-alpine-select::default wire:model="field" :options="$options" />

{{-- Lazy sync (on blur/change) --}}
<x-alpine-select::default wire:model.lazy="field" :options="$options" />

{{-- Deferred sync (on form submit) --}}
<x-alpine-select::default wire:model.defer="field" :options="$options" />

Custom Events

Listen to the model-updated event for custom handling:

<div x-data @model-updated="console.log('Selection changed:', $event.detail.value)">
    <x-alpine-select::default wire:model="field" :options="$options" />
</div>

Dynamic Options

Update options dynamically from your Livewire component:

class MyComponent extends Component
{
    public $selectedCity;
    public $cities = [];

    public function mount()
    {
        $this->cities = City::pluck('name', 'id')->toArray();
    }

    public function render()
    {
        return view('livewire.my-component');
    }
}

<x-alpine-select::default
    wire:model="selectedCity"
    :options="$cities"
/>

Publishing Assets

Publish Configuration

php artisan vendor:publish --tag=alpine-select-config

This publishes config/alpine-select.php for custom configuration.

Publish Views

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

This publishes views to resources/views/vendor/alpine-select for customization.

Publish Translations

php artisan vendor:publish --tag=alpine-select-lang

This publishes language files to lang/vendor/alpine-select for translation.

Publish All

php artisan vendor:publish --provider="Uluumbch\AlpineSelectLivewire\AlpineSelectLivewireServiceProvider"

Translations

The package supports multiple languages. Default texts are in English.

Available Translation Keys

• placeholder - "Select an option..."
• no_results - "No results found"
• search_placeholder - "Search..."
• select_all - "Select All"
• clear_all - "Clear All"

Creating Custom Translations

1. Publish the language files:

php artisan vendor:publish --tag=alpine-select-lang

1. Create your language file (e.g., lang/vendor/alpine-select/id/alpine-select.php):

<?php

return [
    'placeholder' => 'Pilih opsi...',
    'no_results' => 'Tidak ada hasil',
    'search_placeholder' => 'Cari...',
    'select_all' => 'Pilih Semua',
    'clear_all' => 'Hapus Semua',
];

Overriding Translations Per Component

You can override translations for individual components:

<x-alpine-select::default
    wire:model="selectedOption"
    :options="$options"
    placeholder="Custom placeholder text"
    no_results_text="Custom no results message"
    search_placeholder="Custom search placeholder"
/>

Styling Customization

Option 1: TailwindCSS Theme Extension

Customize colors by extending your TailwindCSS theme:

// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        // Override zinc colors
        zinc: {
          // ... your custom shades
        },
        // Override blue accent colors
        blue: {
          // ... your custom shades
        }
      }
    }
  }
}

Option 2: Publish and Modify Views

Publish the views to your application for full control:

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

Views will be published to resources/views/vendor/alpine-select/components/.

Then modify the Blade files directly. Example color scheme change:

# Change from zinc/blue to slate/indigo
cd resources/views/vendor/alpine-select/components
sed -i 's/zinc-/slate-/g' *.blade.php
sed -i 's/blue-/indigo-/g' *.blade.php

Option 3: Custom CSS Overrides

Add custom CSS targeting component classes:

/* resources/css/app.css */
.alpine-select-trigger {
  @apply border-2 border-purple-300 rounded-xl;
}

.alpine-select-option:hover {
  @apply bg-purple-100;
}

Common Customizations

Change dropdown max height:

Find max-h-48 in the component and change to your preferred height class.

Customize icons:

Replace the SVG elements in the published views with your own icons or icon library.

Adjust border radius:

Change rounded-lg to rounded-xl, rounded-2xl, etc.

Troubleshooting

Options not updating

Make sure options are passed as a PHP array or collection, not a JSON string:

{{-- ✅ Correct --}}
:options="$options"

{{-- ❌ Wrong --}}
options="{{ json_encode($options) }}"

Selected value not persisting

Ensure your Livewire property is public and properly initialized:

class MyComponent extends Component
{
    public $selectedOption = ''; // Initialize with empty string or default value
}

Dropdown positioning issues in modals

For dropdowns inside modals or scrollable containers, use floating="false":

<x-alpine-select::default
    wire:model="field"
    :options="$options"
    :floating="false"
/>

Multi-select drag conflicts with Livewire

The multi-select component includes wire:ignore to prevent conflicts. If you still experience issues, ensure you're using Livewire 3.x and the latest package version.

License

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

Credits

• uluumbch - Package author
• Inspired by modern select libraries and Laravel Livewire ecosystem

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue on GitHub.