Filament Searchable Input

https://github.com/defstudio/filament-searchable-input
Admin
Filament Searchable Input is a Laravel package that provides a customizable, searchable autocomplete...
Tokens:35,563
Snippets:262
Trust Score:9.5
License:MIT
Update:2 hours ago
Show doc for...
Tokens:
Raw
### Example: searchUsing with Filament utility injection

Source: https://github.com/defstudio/filament-searchable-input

Demonstrates a searchUsing closure that receives Filament utilities like Get, Set, $state, $component, $record, and $operation. The closure filters products by description and handles create operation.

```php
SearchableInput::make('description')
    ->searchUsing(function (string $search, Get $get, Set $set, $state, $component, ?Model $record, string $operation) {
        // $search: typed query; $get/$set/...: Filament utilities
        return Product::query()
            ->where('description', 'like', "%$search%")
            ->when($operation === 'create', fn ($q) => $q->whereNull('deleted_at'))
            ->limit(15)
            ->pluck('description')
            ->values()
            ->toArray();
    });
```

--------------------------------

### Example: options with value/label pairs

Source: https://github.com/defstudio/filament-searchable-input

Shows how to provide options as a value⇒label map. The value is inserted into the field, the label is displayed.

```php
SearchableInput::make('description')
    ->options([
        'Lorem ipsum dolor' => '[A001] Lorem ipsum dolor.',
        'Aspernatur labore qui fugiat' => '[A001] Aspernatur labore qui fugiat.',
    ]);
```

--------------------------------

### configurePackage(Package $package): void

Source: https://github.com/defstudio/filament-searchable-input

Configures the package using Spatie Laravel Package Tools. Registers the package name, install command, config file, translations, views, and view component conditionally based on file existence. The install command publishes config and migrations, asks to run migrations, and asks to star the GitHub repo.

```php
public function configurePackage(Package $package): void
{
    /*
     * This class is a Package Service Provider
     *
     * More info: https://github.com/spatie/laravel-package-tools
     */
    $package->name(static::$name)
        ->hasInstallCommand(function (InstallCommand $command) {
            $command
                ->publishConfigFile()
                ->publishMigrations()
                ->askToRunMigrations()
                ->askToStarRepoOnGitHub('defstudio/filament-searchable-input');
        });

    $configFileName = $package->shortName();

    if (file_exists($package->basePath("/../config/$configFileName.php"))) {
        $package->hasConfigFile();
    }

    if (file_exists($package->basePath('/../resources/lang'))) {
        $package->hasTranslations();
    }

    if (file_exists($package->basePath('/../resources/views'))) {
        $package->hasViews(static::$viewNamespace);
        $package->hasViewComponent(static::$viewNamespace, Wrapper::class);
    }
}
```

--------------------------------

### Install via Composer

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Install the package using Composer. Requires Filament 3.x, 4.x, or 5.x depending on package version.

```bash
composer require defstudio/filament-searchable-input
```

--------------------------------

### onItemSelected usage example

Source: https://github.com/defstudio/filament-searchable-input

Example of using onItemSelected to add the selected product to a cart. The callback receives a SearchResult and uses the get method to retrieve the product_id.

```php
->onItemSelected(fn (SearchResult $item) => $this->cart->add($item->get('product_id')))
```

--------------------------------

### make() example from array with metadata

Source: https://github.com/defstudio/filament-searchable-input

Creates a SearchResult from a pre-built array with 'value', 'label', and optional 'data'. The 'data' array is accessible via get('unit_id').

```php
$r = SearchResult::make([
    'value' => 'EA',
    'label' => 'Each',
    'data' => ['unit_id' => 3],
]);
// $r->get('unit_id') === 3
```

--------------------------------

### Example: consume selected metadata with onItemSelected

Source: https://github.com/defstudio/filament-searchable-input

Shows how to use onItemSelected to log selected product metadata. The closure receives a SearchResult with value, label, and custom data.

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;
use DefStudio\SearchableInput\DTO\SearchResult;

SearchableInput::make('product')
    ->searchUsing(fn (string $search) => Product::query()
        ->where('name', 'like', "%$search%")
        ->limit(15)
        ->map(fn (Product $p) => SearchResult::make($p->name, "[$p->code] $p->name")
            ->withData('product_id', $p->id))
        ->toArray())
    ->onItemSelected(function (SearchResult $item) {
        Log::info('Product selected', [
            'value' => $item->value(),
            'label' => $item->label(),
            'product_id' => $item->get('product_id'),
        ]);
    });
```

--------------------------------

### Publish views with artisan vendor:publish

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Run this command to publish the package views for customization. The tag is 'filament-searchable-input-views'.

```bash
php artisan vendor:publish --tag="filament-searchable-input-views"
```

--------------------------------

### setUp() lifecycle hook

Source: https://github.com/defstudio/filament-searchable-input

Called automatically by Filament when the component is created. Configures the field to render with the custom wrapper view 'searchable-input-wrapper' and binds x-model="value" on the underlying input so the Alpine component can access the field state.

```php
protected function setUp(): void
{
    $this->fieldWrapperView('searchable-input-wrapper');

    $this->extraInputAttributes(['x-model' => 'value']);
}
```

--------------------------------

### Basic SearchableInput usage with options

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Basic implementation of SearchableInput in a Filament form. It extends TextInput, so all TextInput methods are available. The options method defines a list of selectable strings.

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;

class ProductResource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            SearchableInput::make('description')
                ->options([
                    'Lorem ipsum dolor',
                    'Aspernatur labore qui fugiat',
                    'Dolores tempora libero assumenda',
                    'Qui rem voluptas officiis ut non',
                    
                    //..
                    
                ])
        ]);
    }
}
```

--------------------------------

### Basic usage with plain options

Source: https://github.com/defstudio/filament-searchable-input

Example of creating a SearchableInput with a list of plain options. No server callback is required; the fallback filtering in getSearchResultsForJs handles matching. When the user types 'asper', the method returns matching SearchResult entries and the dropdown shows them.

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;

SearchableInput::make('description')
    ->options([
        'Lorem ipsum dolor',
        'Aspernatur labore qui fugiat',
    ]);
```

--------------------------------

### withData usage example

Source: https://github.com/defstudio/filament-searchable-input

Shows dot-notation chaining and bulk replacement of the data map. The first chain sets nested keys, the second replaces all previous data.

```php
SearchResult::make('FT', 'Feet')
    ->withData('product.id', 5)          // data = ['product' => ['id' => 5]]
    ->withData('product.code', 'FT-5')   // data = ['product' => ['id' => 5, 'code' => 'FT-5']]

// bulk replace:
$r = SearchResult::make('FT', 'Feet');
$r->withData(['a' => 1, 'b' => 2]);      // replaces all previous data
```

--------------------------------

### Complex Items

Source: https://github.com/defstudio/filament-searchable-input/blob/main/FILAMENT_README.md

Use arrays as search results to pass metadata to the selected item and consume it in the onItemSelected method.

```APIDOC
## Complex Items

### Description
Use arrays as search results to pass metadata to the selected item and consume it in the `onItemSelected` method.

### Method
`searchUsing` and `onItemSelected`

### Parameters
- **searchUsing callback** (Closure) - Required - A closure that receives the search string and returns an array of `SearchResult` objects.
- **onItemSelected callback** (Closure) - Required - A closure that receives the selected `SearchResult` item.

### Response
Returns an array of `SearchResult` objects.

### Request Example
```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;
use DefStudio\SearchableInput\DTO\SearchResult;

class ProductResource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            SearchableInput::make('description')
                ->searchUsing(function(string $search){
               
                    return Product::query()
                        ->where('description', 'like', "%$search%")
                        ->limit(15)
                        ->map(fn(Product $product) => SearchResult::make($product->description, "[$product->code] $product->description")
                            ->withData('product_id', $product->id)
                            ->withData('product_code', $product->code) 
                        )
                        ->toArray()
                        
                })
                ->onItemSelected(function(SearchResult $item){
                    $item->value();
                    $item->label();
                    $item->get('product_id');
                    $item->get('product_code');
                }),
        ]);
    }
}
```
```

--------------------------------

### Custom search function with SearchableInput::searchUsing

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Use the searchUsing method to define a custom search query. The closure receives the search string and can return a plain array of values, an associative array, or an array of complex items. The example shows two alternative return types within the same closure, but only the first return is executed; the second is unreachable code.

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;

class ProductResource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            SearchableInput::make('description')
                ->searchUsing(function(string $search){
                
                    return Product::query()
                        ->where('description', 'like', "%$search%")
                        ->orWhere('code', 'like', "%$search%")
                        ->limit(15)
                        ->pluck('description')
                        ->values()
                        ->toArray();
                        
                    // Or, an associative array as well...
                    
                    return Product::query()
                        ->where('description', 'like', "%$search%")
                        ->orWhere('code', 'like', "%$search%")
                        ->limit(15)
                        ->mapWithKeys(fn(Product $product) => [
                            $product->description => "[$product->code] $product->description"
                        ])
                        ->toArray();            
                        
                        
                    // Or, also, an array of complex items (see below)
                })
        ]);
    }
}
```

--------------------------------

### Value-Label pairs options

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Options can be defined as an array of Value and Label pairs. The Value is inserted into the input field when selected, while the Label is only used for display in the search dropdown.

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;

class ProductResource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            SearchableInput::make('description')
                ->options([
                    'Lorem ipsum dolor' => '[A001] Lorem ipsum dolor.',
                    'Aspernatur labore qui fugiat' => '[A001] Aspernatur labore qui fugiat.',
                    'Dolores tempora libero assumenda' => '[A002] Dolores tempora libero assumenda.',
                    'Qui rem voluptas officiis ut non' => '[A003] Qui rem voluptas officiis ut non.',
                    
                    //..
                    
                ])
        ]);
    }
}
```

--------------------------------

### Complex items with SearchResult and onItemSelected

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Use SearchResult objects to pass metadata with search results. The searchUsing closure returns an array of SearchResult instances, each with a value, label, and additional data. The onItemSelected method receives the selected SearchResult and can access its value, label, and custom data via get().

```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;
use DefStudio\SearchableInput\DTO\SearchResult;

class ProductResource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            SearchableInput::make('description')
                ->searchUsing(function(string $search){
               
                    return Product::query()
                        ->where('description', 'like', "%$search%")
                        ->limit(15)
                        ->map(fn(Product $product) => SearchResult::make($product->description, "[$product->code] $product->description")
                            ->withData('product_id', $product->id)
                            ->withData('product_code', $product->code) 
                        )
                        ->toArray()
                        
                })
                ->onItemSelected(function(SearchResult $item){
                    $item->value();
                    $item->label();
                    $item->get('product_id');
                    $item->get('product_code');
                }),
        ]);
    }
}
```

--------------------------------

### SearchableInput::make() with Filament utility injection

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Shows how to use Filament utility injection in the searchUsing() method of SearchableInput. The $options parameter contains the options defined via ->options([...]), and $get/$set are Filament utilities. Other injectable parameters include $state (current field state), $component (current component instance), $record (current form record, ?Model), and $operation (current form operation, e.g., create/update).

```php
 SearchableInput::make('description')
    ->searchUsing(function(string $search, array $options){ //options defined in ->options([...]) 
        //...
    })
    ->searchUsing(function(string $search, Get $get, Set $set){ //$get and $set utilities
        //...
    })
    ->searchUsing(function(string $search, $state){ //current field state
        //...
    })
     ->searchUsing(function(string $search, Component $component){ //current component instance
        //...
    })
     ->searchUsing(function(string $search, ?Model $record){ //current form record
        //...
    })
     ->searchUsing(function(string $search, string $operation){ //current form operation (create/update)
        //...
    });
                
```

--------------------------------

### make() example from string

Source: https://github.com/defstudio/filament-searchable-input

Creates a SearchResult from a plain string; the label defaults to the value. The resulting object has value() and label() both returning 'EA'.

```php
use DefStudio\SearchableInput\DTO\SearchResult;

$r = SearchResult::make('EA');
// $r->value() === 'EA', $r->label() === 'EA'
```

--------------------------------

### SearchableInput::searchUsing()

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Customizes the search result set for a SearchableInput field. The callback receives the search string and should return an array of strings or an associative array of labels to values.

```APIDOC
## [CUSTOM] SearchableInput::searchUsing()

### Description
Customizes the search result set for a SearchableInput field. The callback receives the search string and should return an array of strings or an associative array of labels to values.

### Method
Custom (Filament form component method)

### Parameters
#### Callback Parameters
- **$search** (string) - Required - The search string entered by the user.

### Return Value
- **array** - An array of strings (values) or an associative array mapping values to labels.

### Request Example
```php
SearchableInput::make('description')
    ->searchUsing(function(string $search){
        return Product::query()
            ->where('description', 'like', "%$search%")
            ->orWhere('code', 'like', "%$search%")
            ->limit(15)
            ->pluck('description')
            ->values()
            ->toArray();
    })
```
```

--------------------------------

### SearchableInput::onItemSelected()

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Handles the selection of a complex search result item. The callback receives a SearchResult DTO with methods to access the value, label, and additional data.

```APIDOC
## [CUSTOM] SearchableInput::onItemSelected()

### Description
Handles the selection of a complex search result item. The callback receives a SearchResult DTO with methods to access the value, label, and additional data.

### Method
Custom (Filament form component method)

### Parameters
#### Callback Parameters
- **$item** (SearchResult) - Required - The selected search result item.

### Return Value
- **void** - No return value.

### Request Example
```php
SearchableInput::make('description')
    ->searchUsing(function(string $search){
        return Product::query()
            ->where('description', 'like', "%$search%")
            ->limit(15)
            ->map(fn(Product $product) => SearchResult::make($product->description, "[$product->code] $product->description")
                ->withData('product_id', $product->id)
                ->withData('product_code', $product->code)
            )
            ->toArray();
    })
    ->onItemSelected(function(SearchResult $item){
        $item->value();
        $item->label();
        $item->get('product_id');
        $item->get('product_code');
    })
```
```

--------------------------------

### Custom search with disabled guard

Source: https://github.com/defstudio/filament-searchable-input

Example of using searchUsing to define custom search logic and invoking getSearchResultsForJs directly. The disabled() call acts as a server-side guard; when disabled, the RPC returns []. Otherwise, it returns a list of SearchResult instances.

```php
$field = SearchableInput::make('code')
    ->searchUsing(fn (string $search, $record) => $search === ''
        ? []
        : Product::query()
            ->where('code', 'like', "%$search%")
            ->limit(15)
            ->map(fn (Product $p) => SearchResult::make($p->code, "[$p->code] $p->name"))
            ->toArray());

$field->disabled(); // server-side guard — the RPC returns [] when disabled

$results = $field->getSearchResultsForJs('ABC'); // [] when disabled, else SearchResult list
```

--------------------------------

### HTML option labels with allowHtml()

Source: https://github.com/defstudio/filament-searchable-input/blob/main/README.md

Use allowHtml() to render option labels as HTML in the search dropdown. Only the label is rendered as HTML; the value inserted remains plain text. Can be enabled conditionally with a boolean or closure. Only enable for trusted labels to prevent XSS.

```php
SearchableInput::make('StockUom')
    ->allowHtml()
    ->options([
        'EA' => '<strong>EA</strong> <span>Each</span>',
        'FT' => '<strong>FT</strong> <span>Feet</span>',
    ]);
```

--------------------------------

### Testing SearchableInput field state with Livewire

Source: https://github.com/defstudio/filament-searchable-input

Example of exercising the field state through Livewire using Filament/Livewire test APIs. No package-specific helpers are available yet.

```php
use Livewire\Livewire;

Livewire::test(ProductCreate::class)
    ->fillForm([
        'description' => 'Lorem ipsum dolor',
    ])
    ->assertFormSet([
        'description' => 'Lorem ipsum dolor',
    ]);
```

--------------------------------

### get method implementation

Source: https://github.com/defstudio/filament-searchable-input

Retrieves a metadata value from the data map using dot notation, returning a default if the key is absent.

```php
public function get(string $key, mixed $default = null): mixed
{
    return data_get($this->data, $key, $default);
}
```

--------------------------------

### fromArray() example

Source: https://github.com/defstudio/filament-searchable-input

Creates a SearchResult from an array with 'value', 'label', and 'data'. The label can contain HTML markup.

```php
$item = SearchResult::fromArray([
    'value' => 'EA',
    'label' => '<strong>Each</strong>',
    'data' => ['unit_id' => 1],
]);
```

--------------------------------

### get(string $key, mixed $default = null): mixed

Source: https://github.com/defstudio/filament-searchable-input

Retrieves a metadata value from the data map using dot notation, with an optional default if the key is absent.

```APIDOC
## get(string $key, mixed $default = null): mixed

### Description
Retrieves a metadata value from the data map using dot notation, with an optional default if the key is absent.

### Method
get

### Parameters
- `$key` (string) - Required - Dot-notation key into the `data` map
- `$default` (mixed) - Optional - Returned when the key is absent

### Returns
`mixed` — the metadata value at `$key`, or `$default`.
```

--------------------------------

### SearchableInput::searchUsing

Source: https://github.com/defstudio/filament-searchable-input/blob/main/docs/6.usage.md

Configures the search behavior for a SearchableInput field. The callback receives the search string and can optionally receive additional Filament utilities such as $get, $set, $state, $component, $record, and $operation.

```APIDOC
## SearchableInput::searchUsing

### Description
Configures the search behavior for a SearchableInput field. The callback receives the search string and can optionally receive additional Filament utilities such as $get, $set, $state, $component, $record, and $operation.

### Method
`searchUsing`

### Parameters
- **$search** (string) - Required - The search query string.
- **$options** (array) - Optional - Options defined via `->options([...])`.
- **$get** (Get) - Optional - Filament utility to retrieve sibling field values.
- **$set** (Set) - Optional - Filament utility to set sibling field values.
- **$state** (mixed) - Optional - Current field state.
- **$component** (Component) - Optional - Current component instance.
- **$record** (?Model) - Optional - Current form record.
- **$operation** (string) - Optional - Current form operation (create/update).

### Example
```php
SearchableInput::make('description')
    ->searchUsing(function(string $search, array $options){ //options defined in ->options([...]) 
        //...
    })
    ->searchUsing(function(string $search, Get $get, Set $set){ //$get and $set utilities
        //...
    })
    ->searchUsing(function(string $search, $state){ //current field state
        //...
    })
     ->searchUsing(function(string $search, Component $component){ //current component instance
        //...
    })
     ->searchUsing(function(string $search, ?Model $record){ //current form record
        //...
    })
     ->searchUsing(function(string $search, string $operation){ //current form operation (create/update)
        //...
    });
```
```

--------------------------------

### packageBooted(): void

Source: https://github.com/defstudio/filament-searchable-input

Registers assets, script data, icons, publishes stubs in console, and mixes TestsSearchableInput into Testable. The stub publishing uses the 'filament-searchable-input-stubs' tag.

```php
public function packageBooted(): void
{
    // Asset Registration
    FilamentAsset::register(
        $this->getAssets(),
        $this->getAssetPackageName()
    );

    FilamentAsset::registerScriptData(
        $this->getScriptData(),
        $this->getAssetPackageName()
    );

    // Icon Registration
    FilamentIcon::register($this->getIcons());

    // Handle Stubs
    if (app()->runningInConsole()) {
        foreach (app(Filesystem::class)->files(__DIR__ . '/../stubs/') as $file) {
            $this->publishes([
                $file->getRealPath() => base_path("stubs/filament-searchable-input/{$file->getFilename()}"),
            ], 'filament-searchable-input-stubs');
        }
    }

    // Testing
    Testable::mixin(new TestsSearchableInput);
}
```

--------------------------------

### Empty config file for DefStudio/SearchableInput

Source: https://github.com/defstudio/filament-searchable-input

The shipped config file at config/searchable-input.php is empty, with no option keys defined. No code in src/ reads config('searchable-input.*'), so it only reserves the configuration surface for future versions.

```php
<?php

// config for DefStudio/SearchableInput
return [

];
```

--------------------------------

### options method

Source: https://github.com/defstudio/filament-searchable-input

Sets the options as a list or value⇒label map, or a closure returning such an array. Returns $this for chaining.

```php
/**
 * @param  array<array-key, string>|Closure(): array<array-key, string>|null  $options
 */
public function options(array | Closure | null $options): static
{
    $this->options = $options;

    return $this;
}
```

--------------------------------

### Empty translations file for searchable-input

Source: https://github.com/defstudio/filament-searchable-input

Ships empty by default; add your translation keys here. Registered only when the resources/lang directory exists.

```php
<?php

// translations for DefStudio/SearchableInput
return [
    //
];
```

--------------------------------

### packageRegistered(): void

Source: https://github.com/defstudio/filament-searchable-input

Hook invoked by the parent when the package is registered. Empty in this package.

```php
public function packageRegistered(): void {}
```

--------------------------------

### getOptions method

Source: https://github.com/defstudio/filament-searchable-input

Resolves the options array, evaluating the options closure if set. Sets $optionsIsList to true when the result is a list; note that an empty result later does not reset the flag.

```php
/**
 * @return array<array-key, string>
 */
public function getOptions(): array
{
    $options = $this->evaluate($this->options) ?? [];

    if (array_is_list($options)) {
        $this->optionsIsList = true;
    }

    return $options;
}
```

--------------------------------

### options(array | Closure | null $options): static

Source: https://github.com/defstudio/filament-searchable-input

Sets the options for the component, either as a list or a value⇒label map, or a closure that returns such an array. Returns the component instance for chaining.

```APIDOC
## options(array | Closure | null $options): static

### Description
Sets the options for the component, either as a list or a value⇒label map, or a closure that returns such an array. Returns the component instance for chaining.

### Method
RPC (Livewire)

### Endpoint
`options`

### Parameters
#### Request Body
- `$options` (array<array-key, string> | Closure(): array<array-key, string> | null) - Required - Options as a list (`['A', 'B']`) or value⇒label map (`['A' => 'Label A']`); closure form supports Filament utility injection

### Response
#### Success Response
- Returns `static` — `$this` for chaining.

### Request Example
```php
SearchableInput::make('description')
    ->options([
        'Lorem ipsum dolor' => '[A001] Lorem ipsum dolor.',
        'Aspernatur labore qui fugiat' => '[A001] Aspernatur labore qui fugiat.',
    ]);
```
```

--------------------------------

### getRoutes(): array

Source: https://github.com/defstudio/filament-searchable-input

Returns an empty array, indicating no HTTP routes are exposed by the package. Only Livewire schema-component methods are available.

```php
/**
 * @return array<string>
 */
protected function getRoutes(): array
{
    return [];
}
```

--------------------------------

### SearchableInput::make with options

Source: https://github.com/defstudio/filament-searchable-input/blob/main/docs/0.index.md

Basic usage of the SearchableInput form field, providing a static list of options for autocomplete. The options array contains string values; the field renders a searchable input in Filament forms.

```php
SearchableInput::make('description')
    ->options([
        'Lorem ipsum dolor',
        'Aspernatur labore qui fugiat',
        'Dolores tempora libero assumenda',
        'Qui rem voluptas officiis ut non', 
        //..         
    ])
```

--------------------------------

### searchUsing(?Closure $searchUsing): static

Source: https://github.com/defstudio/filament-searchable-input

Sets a custom search callback that returns options based on the search query. The callback may return a list, a value⇒label map, or SearchResult instances, or null to fall back to substring filtering.

```APIDOC
## searchUsing(?Closure $searchUsing): static

### Description
Sets a custom search callback that returns options based on the search query. The callback may return a list, a value⇒label map, or SearchResult instances, or null to fall back to substring filtering.

### Method
RPC (Livewire)

### Endpoint
`searchUsing`

### Parameters
#### Request Body
- `$searchUsing` (?Closure(string): ?array<int|string, string|SearchResult>) - Required - Callback `fn (string $search, ...) : ?array`; may return a list, a value⇒label map, or `SearchResult` items. `null` disables the custom callback (fallback filtering applies).

### Response
#### Success Response
- Returns `static` — `$this` for chaining.

### Request Example
```php
SearchableInput::make('description')
    ->searchUsing(function (string $search, Get $get, Set $set, $state, $component, ?Model $record, string $operation) {
        // $search: typed query; $get/$set/...: Filament utilities
        return Product::query()
            ->where('description', 'like', "%$search%")
            ->when($operation === 'create', fn ($q) => $q->whereNull('deleted_at'))
            ->limit(15)
            ->pluck('description')
            ->values()
            ->toArray();
    });
```
```

--------------------------------

### getAssets(): array

Source: https://github.com/defstudio/filament-searchable-input

Registers the compiled Alpine component with key 'filament-searchable-input' pointing at resources/dist/filament-searchable-input.js. Returns an array of Filament\Support\Assets\Asset.

```php
/**
 * @return array<Asset>
 */
protected function getAssets(): array
{
    return [
        AlpineComponent::make('filament-searchable-input', __DIR__ . '/../resources/dist/filament-searchable-input.js'),
    ];
}
```

--------------------------------

### getOptions(): array

Source: https://github.com/defstudio/filament-searchable-input

Resolves the options for the component, evaluating the options closure if set, otherwise returning the plain array. Sets a flag indicating whether the resolved array is a list.

```APIDOC
## getOptions(): array

### Description
Resolves the options for the component, evaluating the `options` closure if one was set, otherwise returning the plain array. Side effect: sets `$optionsIsList` to `true` when the resolved array is a list.

### Method
RPC (Livewire)

### Endpoint
`getOptions`

### Response
#### Success Response
- Returns `array<array-key, string>` — the resolved options. Side effect: sets `$optionsIsList` to `true` when the resolved array is a list. Note: calling this with an empty result later on does not reset the flag.
```

--------------------------------

### make() method implementation

Source: https://github.com/defstudio/filament-searchable-input

Static factory that creates a SearchResult from a string, array, or existing SearchResult. For arrays, it expects 'value' and 'label' keys and optional 'data'; missing keys raise 'Undefined array key' errors. For SearchResult input, it returns the same instance (pass-through).

```php
public static function make(string | array | SearchResult $value, ?string $label = null): self
{
    if (is_array($value)) {
        $searchResult = new SearchResult($value['value'], $value['label']);
        $searchResult->data = $value['data'];

        return $searchResult;
    }

    if ($value instanceof SearchResult) {
        return $value;
    }

    return new static($value, $label ?? $value);
}
```

--------------------------------

### getAssetPackageName(): ?string

Source: https://github.com/defstudio/filament-searchable-input

Returns the asset package namespace 'defstudio/filament-searchable-input' used for Filament asset registration. It is the second argument of FilamentAsset::getAlpineComponentSrc in the blade view.

```php
protected function getAssetPackageName(): ?string
{
    return 'defstudio/filament-searchable-input';
}
```

--------------------------------

### getIcons(): array

Source: https://github.com/defstudio/filament-searchable-input

Returns an empty array, indicating no icons are registered.

```php
/**
 * @return array<string>
 */
protected function getIcons(): array
{
    return [];
}
```

--------------------------------

### reactOnItemSelectedFromJs Livewire RPC method

Source: https://github.com/defstudio/filament-searchable-input

Exposed Livewire method called by the Alpine component when a suggestion is chosen. Evaluates the onItemSelected closure with the item injected as a SearchResult.

```php
#[ExposedLivewireMethod]
public function reactOnItemSelectedFromJs(array $item): void
{
    $this->evaluate($this->onItemSelected, [
        'item' => SearchResult::fromArray($item),
    ]);
}
```

--------------------------------

### Conditional config registration in SearchableInputServiceProvider

Source: https://github.com/defstudio/filament-searchable-input

Registers the config file only if config/filament-searchable-input.php exists. Since the repository ships config/searchable-input.php (different filename), the conditional is not triggered, so no config is registered or published by default.

```php
$configFileName = $package->shortName();

if (file_exists($package->basePath("/../config/$configFileName.php"))) {
    $package->hasConfigFile();
}
```

--------------------------------

### getSearchResultsForJs() Livewire RPC method

Source: https://github.com/defstudio/filament-searchable-input

Livewire RPC endpoint called by the Alpine component with { search: value }. Returns an array of SearchResult instances. If the field is disabled or read-only, returns []. Evaluates the searchUsing closure if set; otherwise falls back to case-insensitive substring filtering of option values. Normalizes items into SearchResult instances based on whether options are a list or associative.

```php
#[ExposedLivewireMethod]
#[Renderless]
public function getSearchResultsForJs(string $search): array
{
    if ($this->isDisabled() || $this->isReadOnly()) {
        return [];
    }

    $results = $this->evaluate($this->searchUsing, [
        'search' => $search,
        'options' => $this->getOptions(),
    ]);

    $results ??= collect($this->getOptions())
        ->filter(fn (string $option) => str($option)->contains($search, true))
        ->toArray();

    if ($this->optionsIsList) {
        $results = collect($results)
            ->map(fn ($item) => $item instanceof SearchResult ? $item : SearchResult::make($item))
            ->toArray();
    } else {
        $results = collect($results)
            ->map(fn ($item, $key) => $item instanceof SearchResult ? $item : SearchResult::make($key, $item))
            ->toArray();
    }

    return array_values($results);
}
```

--------------------------------

### Blade template for dropdown suggestions with Alpine x-for

Source: https://github.com/defstudio/filament-searchable-input

Renders one <li> per suggestion using Alpine's x-for. Displays suggestion.label as text or HTML depending on isHtmlAllowed(), and calls set(suggestion) on click. suggestion.value is inserted into the field on selection; suggestion.data is not consumed client-side but round-trips to the server.

```blade
<template x-for="(suggestion, index) in suggestions">
    <li x-bind:class="{ 'def-fo-searchable-input-dropdown-list-item-selected ...': selected_suggestion === index }"
        @if ($field->isHtmlAllowed())
            x-html="`${suggestion.label}`"
        @else
            x-text="`${suggestion.label}`"
        @endif
        x-on:click="set(suggestion)"
    ></li>
</template>
```

--------------------------------

### Registering TestsSearchableInput mixin

Source: https://github.com/defstudio/filament-searchable-input

Registers the mixin on Testable in packageBooted(). Applies globally to every Livewire Testable instance.

```php
Testable::mixin(new TestsSearchableInput);
```

--------------------------------

### SearchableInput $options property docblock

Source: https://github.com/defstudio/filament-searchable-input

Docblock for the $options property in SearchableInput.php. Accepts an array of strings or a closure returning such an array, or null.

```php
/** @var array<array-key, string>|Closure(): ?array<array-key, string>|null */
protected array | Closure | null $options = null;
```

--------------------------------

### PHP signature for reactOnItemSelectedFromJs

Source: https://github.com/defstudio/filament-searchable-input

Declares the Livewire-exposed method that accepts the full suggestion payload and triggers the onItemSelected closure. Requires the item array; item.value is mandatory, item.label defaults to value, item.data defaults to {}.

```php
#[ExposedLivewireMethod]
public function reactOnItemSelectedFromJs(array $item): void
```

--------------------------------

### reactOnItemSelectedFromJs(array $item): void

Source: https://github.com/defstudio/filament-searchable-input

Livewire RPC endpoint called by the Alpine component when a suggestion is chosen. Evaluates the onItemSelected closure with the selected item injected as a SearchResult.

```APIDOC
## reactOnItemSelectedFromJs(array $item): void

### Description
Livewire RPC endpoint (`#[ExposedLivewireMethod]`) called by the Alpine component when a suggestion is chosen. Evaluates the `onItemSelected` closure with `item` injected as a `SearchResult`.

### Method
RPC (Livewire)

### Endpoint
`reactOnItemSelectedFromJs`

### Parameters
#### Request Body
- `$item` (array) - Required - Wire payload holding at least `value` and `label`, plus optional `data` (the `SearchResult::toArray()` shape)

### Response
#### Success Response
- Returns `void`. Side effect: evaluates the `onItemSelected` closure with `item` injected as a `SearchResult`.

### Request Example
```php
use DefStudio\SearchableInput\Forms\Components\SearchableInput;
use DefStudio\SearchableInput\DTO\SearchResult;

SearchableInput::make('product')
    ->searchUsing(fn (string $search) => Product::query()
        ->where('name', 'like', "%$search%")
        ->limit(15)
        ->map(fn (Product $p) => SearchResult::make($p->name, "[$p->code] $p->name")
            ->withData('product_id', $p->id))
        ->toArray())
    ->onItemSelected(function (SearchResult $item) {
        Log::info('Product selected', [
            'value' => $item->value(),
            'label' => $item->label(),
            'product_id' => $item->get('product_id'),
        ]);
    });
```
```

--------------------------------

### next_suggestion() - navigate down

Source: https://github.com/defstudio/filament-searchable-input

Bound to keydown.down. Increments selected_suggestion, clamped at the last index. With an empty list, value becomes -1 (no visible effect).

```javascript
next_suggestion() {
    this.selected_suggestion++

    if (this.selected_suggestion > this.suggestions.length - 1) {
        this.selected_suggestion = this.suggestions.length - 1
    }
},
```

--------------------------------

### refresh_suggestions() - fetch suggestions via Livewire

Source: https://github.com/defstudio/filament-searchable-input

Triggered from the blade view via x-on:keyup when a non-navigation key is pressed. No-op if value is unchanged; clears suggestions for empty value; otherwise calls getSearchResultsForJs and updates suggestions and selected_suggestion.

```javascript
refresh_suggestions: function() {
    if (this.value === this.previous_value) {
        return
    }

    if (!this.value) {
        this.suggestions = []
        this.previous_value = null
        return
    }

    this.previous_value = this.value

    // noinspection JSPotentiallyInvalidUsageOfThis
    this.$wire.callSchemaComponentMethod(key, 'getSearchResultsForJs', { search: this.value })
        .then(response => {
            this.suggestions = response
            this.selected_suggestion = 0
        })
},
```

--------------------------------

### SearchResult::make()

Source: https://github.com/defstudio/filament-searchable-input

Creates a new SearchResult instance from a string, array, or another SearchResult. This is a static factory method for constructing SearchResult objects.

```APIDOC
## SearchResult::make()

### Description
Creates a new SearchResult instance from a string, array, or another SearchResult. This is a static factory method for constructing SearchResult objects.

### Method
`make`

### Parameters
- `$value` (string|array|SearchResult) - Required - The value to convert into a SearchResult.

### Returns
- `SearchResult` - The created SearchResult instance.
```

--------------------------------

### searchUsing method

Source: https://github.com/defstudio/filament-searchable-input

Sets the search callback. The closure may return a list, an associative map, SearchResult instances, or null to fall back to substring filtering of options. Returns $this for chaining.

```php
/**
 * @param  ?Closure(string): ?array<int|string, string|SearchResult>  $searchUsing
 */
public function searchUsing(?Closure $searchUsing): static
{
    $this->searchUsing = $searchUsing;

    return $this;
}
```

--------------------------------

### Blade wrapper loading searchableInput Alpine component

Source: https://github.com/defstudio/filament-searchable-input

Loads the compiled Alpine component via Filament's asset loader and initializes it with the field's key and state path. Used by the blade wrapper view.

```blade
x-load
x-load-src="{{ FilamentAsset::getAlpineComponentSrc('filament-searchable-input', 'defstudio/filament-searchable-input') }}"
x-data="searchableInput({ key: '{{$field->getKey()}}', statePath: '{{$field->getStatePath()}}' })"
```

--------------------------------

### SearchResult::make()

Source: https://github.com/defstudio/filament-searchable-input

Static factory to create a SearchResult instance from a string, array, or existing SearchResult. It handles normalization and pass-through for existing instances.

```APIDOC
## SearchResult::make()

### Description
Static factory to create a SearchResult instance from a string, array, or existing SearchResult. It handles normalization and pass-through for existing instances.

### Method
Static method

### Signature
```php
public static function make(string | array | SearchResult $value, ?string $label = null): self
```

### Parameters
- `$value` (string | array{value: string, label: string, data?: array<string, mixed>} | SearchResult) - Required - Either a plain value string, a pre-built array (`value`, `label`, optional `data`), or an existing `SearchResult`
- `$label` (?string) - Optional - Display label; ignored for array/`SearchResult` inputs; defaults to `$value` when omitted

### Returns
`self` - a new instance, or the same `SearchResult` when one was passed in (pass-through).

### Throws
- `Undefined array key "value"` when `$value` is an array without a `'value'` key
- `Undefined array key "label"` when `$value` is an array without a `'label'` key
- `Undefined array key "data"` when `$value` is an array without a `'data'` key (use `SearchResult::fromArray()` when keys may be absent)

### Request Example
```php
use DefStudio\SearchableInput\DTO\SearchResult;

$r = SearchResult::make('EA');
// $r->value() === 'EA', $r->label() === 'EA'
```

```php
$r = SearchResult::make([
    'value' => 'EA',
    'label' => 'Each',
    'data' => ['unit_id' => 3],
]);
// $r->get('unit_id') === 3
```
```

--------------------------------

### PHP signature for getSearchResultsForJs

Source: https://github.com/defstudio/filament-searchable-input

Server method exposed as an RPC endpoint via #[ExposedLivewireMethod] and #[Renderless]. Returns an array of SearchResult instances; short-circuits to [] when the field is disabled or read-only.

```php
#[ExposedLivewireMethod]
#[Renderless]
public function getSearchResultsForJs(string $search): array
```

--------------------------------

### label method implementation

Source: https://github.com/defstudio/filament-searchable-input

Returns the display label for the suggestion.

```php
public function label(): string
{
    return $this->label;
}
```

--------------------------------

### previous_suggestion() - navigate up

Source: https://github.com/defstudio/filament-searchable-input

Bound to keydown.up. Decrements selected_suggestion, clamped at 0.

```javascript
previous_suggestion() {
    this.selected_suggestion--

    if (this.selected_suggestion < 0) {
        this.selected_suggestion = 0
    }
},
```

--------------------------------

### set(item) - select suggestion and notify server

Source: https://github.com/defstudio/filament-searchable-input

Bound to x-on:click on dropdown items and keydown.enter. Writes item.value into entangled state, clears suggestions, and calls reactOnItemSelectedFromJs with the item payload. Ignores undefined item.

```javascript
set: function(item) {
    if (item === undefined) {
        return
    }

    this.value = item.value
    this.suggestions = []

    // noinspection JSPotentiallyInvalidUsageOfThis
    this.$wire.callSchemaComponentMethod(key, 'reactOnItemSelectedFromJs', { item: item })
},
```

--------------------------------

### SearchResult constructor

Source: https://github.com/defstudio/filament-searchable-input

Final constructor that takes a value and label. The value is inserted into the input on selection, the label is the display text in the dropdown. Subclassing is prevented; instances are normally created via the make() static factory.

```php
final public function __construct(
    protected string $value,
    protected string $label,
) {}
```

--------------------------------

### getSearchResultsForJs

Source: https://github.com/defstudio/filament-searchable-input

Retrieves search results for autocomplete suggestions. Called from the front-end via Livewire's schema-component RPC mechanism.

```APIDOC
## [RPC] getSearchResultsForJs

### Description
Retrieves search results for autocomplete suggestions. Called from the front-end via Livewire's schema-component RPC mechanism.

### Method
RPC (Livewire schema-component method)

### Endpoint
`$wire.callSchemaComponentMethod(key, 'getSearchResultsForJs', { search: this.value })`

### Parameters
#### Request Body
- **search** (string) - Required - The raw text typed in the input; the query for search/autocomplete

### Response
#### Success Response (200)
- **top level** (array) - A re-indexed list (`array_values`) of `SearchResult` instances; serialized over the wire to plain objects in `toArray()` shape
- **[].value** (string) - Value inserted into the input on selection
- **[].label** (string) - Display label for the dropdown row (HTML when `allowHtml()` enabled)
- **[].data** (object) - Metadata map attached via `SearchResult::withData()`

### Request Example
```js
// from any Alpine context that has the schema component key
this.$wire.callSchemaComponentMethod('your-field-key', 'getSearchResultsForJs', { search: 'lorem' })
    .then((results) => {
        // results: [{ value: 'Lorem ipsum dolor', label: 'Lorem ipsum dolor', data: {} }, ...]
    });
```
```
Tokens:
Raw