Logo Beartropy UI
Lookup
The x-bt-lookup component is a smart text input with an attached suggestion dropdown.
It supports typeahead filtering, keyboard navigation, and Livewire integration while keeping a simple API.
Pass any kind of options array or collection, and it will normalize them into id/name pairs.

Basic Usage

The simplest usage: pass an array of scalar values (strings, integers, etc.).
Each value will be used as both the option label and value. 

1<x-bt-lookup
2    label="Country"
3    placeholder="Start typing a country..."
4    :options="['Argentina', 'Brasil', 'Chile', 'Uruguay']"
5/>

Associative Arrays

You can also pass an associative array where the key is the value and the array value is the label.
Example: ['ar' => 'Argentina'] becomes id = 'ar', name = 'Argentina'. 

 1<x-bt-lookup
 2    label="Country"
 3    placeholder="Search..."
 4    :options="[
 5        'ar' => 'Argentina',
 6        'br' => 'Brasil',
 7        'cl' => 'Chile',
 8        'uy' => 'Uruguay',
 9    ]"
10/>

Using Models & Custom Fields

When passing models or complex arrays, use option-label and option-value
to choose which fields are displayed and which ones are stored. 

1<x-bt-lookup
2    label="User"
3    placeholder="Search user..."
4    :options="$users"      {{-- e.g. User::all() --}}
5    option-label="name"
6    option-value="id"
7/>

Livewire Integration

When bound with wire:model, the lookup keeps the text input and stored value separated.
The user types and selects by label, while Livewire receives the corresponding option-value.

Selected user id is: None Selected user is: None 
 1<div class="grid grid-cols-1">
 2    <span>Selected user id is: <strong>{{ $userId ? $userId : 'None' }}</strong></span>
 3    <span>Selected user is: <strong>{{ $userId ? \App\Models\UsersForSearch::find($userId)->name : 'None' }}</strong></span>
 4</div>
 5 
 6{{-- Blade view --}}
 7<x-bt-lookup
 8    label="User"
 9    placeholder="Type to search a user..."
10    :options="$users"
11    option-label="name"
12    option-value="id"
13    wire:model.live="userId"
14/>

Props

Prop Type Default Description
options
array|Collection []
Data source for suggestions. It accepts:
  • Simple values: ['Argentina', 'Brasil'] → id and name both use the value.
  • Associative arrays: ['ar' => 'Argentina'] → id='ar', name='Argentina'.
  • Models/arrays: any array/collection where fields exist for option-label and option-value.
Internally everything is normalized into an array of ['id' => ..., 'name' => ...].
option-label
string name
Name of the field used as the display label for each option.
Applied both when normalizing options in PHP and when reading labels in Alpine.
option-value
string id
Name of the field used as the stored value for each option (e.g. primary key).
When used with wire:model, this is what gets sent to Livewire.
label
string|null null
Optional text label displayed above the lookup input.
placeholder
string|null null
Placeholder for the visible text input (search box).
Example: placeholder="Start typing...".
wire:model
Livewire binding null
Binds the lookup to a Livewire property. The component:
  • Maintains a hidden input with the selected option-value (or raw text if there is no exact match).
  • Uses the visible text input only as the search/display value.
  • Dispatches input events when the selected option changes.
x-model
Alpine binding null
Optional external Alpine binding for the visible text value.
When present, the component uses the given Alpine variable instead of its internal value.
clearable
bool true
Adds a clear (X) button to fully reset both the text input and Livewire hidden value.
Internally calls clearBoth() to keep values in sync.
copyButton
bool false
Shows a "copy to clipboard" button in the end slot, copying the visible text value.
type
string text
HTML input type for the visible text input. Usually text for lookups.
size
string|null null
Size preset from the input presets (e.g. sm, md, lg).
color
string|null null
Color preset key. Uses the same presets as x-bt-input.
customError
string|null null
Custom error message to force an error state. Rendered via the field-help component.
hint
string|null null
Optional help text displayed below the field.
iconStart / iconEnd
string|null null
Optional Beartropy icon names rendered inside the input at the start or end.
start / end slots
slot null
Custom content rendered at the start or end of the input. Can be used alongside icons, clear, copy, etc.
Dropdown behavior
internal —
The dropdown opens as you type and filters options by label, ignoring case and accents.
Supports keyboard navigation with ↑/↓, Enter, Tab, and closes on Esc or blur.
Other props
mixed —
All standard x-bt-input props are also available (e.g. spinner, showPasswordToggle for text/password use-cases, etc.).
Code highlighting provided by Torchlight