TextInput Autocomplete

• Screenshots
• Requirements
• Installation
• Usage
  • Static options (filtered client-side)
  • Server search (via Livewire; may call an external API)
  • Item rendering
• Configuration reference
• Styling
• Development
• License

A Filament v5 form field: a free-text input with an autocomplete dropdown. Suggestions can be static (filtered in the browser) or fetched from the server through Livewire. Each suggestion's markup is rendered by PHP via a single itemView() setter.

#Screenshots

Static options (filtered client-side):

Server search (via Livewire, optionally calling an external API):

#Requirements

• PHP 8.2+
• Filament v5

#Installation

composer require giacomomasseron/filament-textinput-autocomplete

The compiled Alpine component and CSS ship in dist/ and are registered with Filament automatically — no npm step is required to use the package. As with any Filament plugin that registers assets, publish them once (and on each deploy) so the stylesheet is served:

php artisan filament:assets

#Usage

#Static options (filtered client-side)

use GiacomoMasseroni\TextInputAutocomplete\Forms\Components\AutocompleteInput;

AutocompleteInput::make('country')
    ->options([
        ['value' => 'es', 'label' => 'Spain', 'description' => 'Country'],
        ['value' => 'fr', 'label' => 'France', 'description' => 'Country'],
    ])
    ->searchKeys(['label', 'description'])
    ->itemView(fn (array $item) => "<strong>{$item['label']}</strong> — {$item['description']}");

#Server search (via Livewire; may call an external API)

use GiacomoMasseroni\TextInputAutocomplete\Forms\Components\AutocompleteInput;
use Illuminate\Support\Facades\Http;

AutocompleteInput::make('repo')
    ->getSearchResultsUsing(function (string $search) {
        $items = Http::get('https://api.github.com/search/repositories', [
            'q' => $search,
        ])->json('items', []);

        return collect($items)
            ->map(fn (array $repo) => [
                'value' => $repo['id'],
                'label' => $repo['full_name'],
            ])
            ->all();
    })
    ->itemView('filament.autocomplete.repo') // a Blade view that receives $item
    ->minChars(2)
    ->searchDebounce(300);

#Item rendering

itemView() accepts three forms, resolved by type:

• Closure — fn (array $item) => '<raw html>'. Returned string is rendered as raw HTML (you are responsible for escaping).
• Blade view name — e.g. 'filament.autocomplete.repo'. The view receives the item as $item.
• Template string — e.g. '{label} — {description}'. {key} tokens are replaced with the matching item values, HTML-escaped.

If itemView() is not set, the item's optionLabel value is shown as escaped text.

#Configuration reference

options() and getSearchResultsUsing() are mutually exclusive — setting both throws an InvalidArgumentException. maxResults must be at least 1.

#Styling

The field ships with a self-contained default style (a light input with a #667eea focus accent and a shadowed dropdown) so it looks consistent out of the box without depending on your panel's theme. It is served as a registered Filament CSS asset (dist/autocomplete.css, published via php artisan filament:assets). The styles are scoped to these classes:

To restyle, override any of these classes in your own stylesheet. Markup inside each suggestion is whatever your itemView() returns, so you control that completely.

#Development

composer install
npm install
npm run build      # rebuild dist/ assets after editing resources/js or resources/css
vendor/bin/pest    # run the test suite

#License

MIT